Inspect database health

Goal. Find out whether a database is sound, and what it contains. About two minutes.

You need. A database path.

The one to run when something is wrong

strata ./mydb doctor

binary     1.2.2
database
  exists   true
  open_ok  true
  path     ./mydb
  info
    branch_count    1
    default_branch  default
    durable         true
    target          durable_local
    version         1.2.2
home       /home/anibjoshi/.strata
inference
  local_execution    false
  models_catalogued  11

doctor checks the installation as well as the database, which is why it is the first thing to run when you do not yet know what is wrong. Three fields carry most of the diagnosis:

path is the path it actually resolved. Compare it to the one you meant.
exists says whether a database is there.
open_ok says whether it opened. false here with exists: true is the signature of a damaged database.

The other four

strata ./mydb describe

StrataDB 1.2.2 · durable_local
branch default · branches: default · spaces: default
capabilities: arrow event graph_core inference json kv vector vector_index
kv 0 · json 0 · events 0

One line each for what it is, where you are, what it can do, and what is in it. This is the orientation command.

strata ./mydb info

Target, version, durability, branch and space counts, and the memory budget with where that budget came from.

strata ./mydb health

status          healthy
identity        healthy
registry        healthy
branch_catalog  healthy
space_catalog   healthy

One line per subsystem. This is the one to assert on in a monitoring check, because it names which part is unhealthy rather than just failing.

strata ./mydb metrics

Counters, for a dashboard.

In a script

All five take --json:

strata --json ./mydb health

That is the stable contract. Global options covers the formats, and --raw if you want tab-separated fields instead.

What it is costing you on disk

admin storage reports the footprint: live tables, snapshots, timeline segments, the WAL, and the reclaim ledger. Durable databases only: a cache database has no disk to account for.

strata ./mydb admin storage --audit

audit                              true
live_table_objects                 0
live_table_bytes                   0 B
unreferenced_objects               0
unreferenced_bytes                 0 B
quarantined_objects                0
quarantined_bytes                  0 B
snapshot_objects                   1
snapshot_bytes                     6.3 kB
superseded_snapshots               0
superseded_snapshot_bytes          0 B
timeline_segment_objects           2
timeline_segment_bytes             1.1 kB
wal_retention_watermark            42
wal_reclaimable_bytes              0 B
wal_tail_bytes                     36 B
total_bytes                        7.4 kB

Without --audit the command answers only what it already knows and prints - for the rest. The audit is what walks the store to stat unreferenced and quarantined objects, the superseded snapshot set, and the WAL’s reclaimable-versus-tail split. Run the plain form for a quick total; run --audit when you want to know what the reclaim runners would actually be able to free.

du -sh ./mydb still tells you what the directory weighs. What it cannot tell you is how much of that is live data and how much is history waiting to be reclaimed, which is the number you usually want.

Databases and storage has what history costs.

Failure modes

exists: true, open_ok: false. The directory is there and the database will not open. Recover from errors.

Everything reports healthy but your data is missing. Check path. A mistyped path is a different, empty database, and it will report perfect health.

Troubleshoot failures.