db/status.ts

Database status utility for CLI and dev workflows.

Queries migration state and table info without a running server. Returns structured data that consumer scripts can print however they like.

The migration check is name-divergence aware: it name-prefix-verifies the applied migrations against the code's list (mirroring run_migrations), so a divergent history (same count, different names) reports a divergence and renders DIVERGED rather than a false up_to_date.

view source

Declarations
#

6 declarations

DbStatus
#

db/status.ts view source

DbStatus import type {DbStatus} from '@fuzdev/fuz_app/db/status.js';

Full database status snapshot.

`connected`

Whether the database is reachable.

type boolean

`error?`

Error message if connection failed.

type string

`table_count`

Number of public tables.

type number

`tables`

Per-table row counts.

type Array<TableStatus>

`migrations`

Per-namespace migration status.

type Array<MigrationStatus>

`old_tracker_shape?`

True if the pre-0.42 schema_version shape (with a version column) was detected. The runner refuses to start in this state — operators see this flag as their cue to drop the table or call baseline().

type boolean

Divergence
#

db/status.ts view source

Divergence import type {Divergence} from '@fuzdev/fuz_app/db/status.js';

A divergence between the recorded migration tracker and the code's list.

Either variant is a state the migration runner refuses to boot against — a re-bootstrap (drop + migrate) is needed. Structured (not a pre-formatted string) so programmatic consumers can branch on kind; format_db_status renders the operator-facing line. The discriminated-union twin of the Rust fuz_db Divergence enum.

format_db_status
#

db/status.ts view source

(status: DbStatus): string import {format_db_status} from '@fuzdev/fuz_app/db/status.js';

Format a DbStatus as a human-readable string for CLI output.

`status`

the status to format

type DbStatus

returns

string

multi-line string suitable for console output

MigrationStatus
#

db/status.ts view source

MigrationStatus import type {MigrationStatus} from '@fuzdev/fuz_app/db/status.js';

Migration status for a single namespace.

`namespace`

type string

`applied_names`

Names of migrations recorded in the tracker, sequence-ascending.

type Array<string>

`pending_names`

Names of code migrations not yet applied (suffix of the code array).

type Array<string>

`up_to_date`

Whether applied_names is the full code array with no name divergence (no pending work, no diverged history).

type boolean

`divergence?`

The first applied/code divergence, if any. Absent when the applied names are a clean prefix of the code's list (the only state the runner boots against). Present means a divergent bootstrap history — a re-bootstrap (drop + migrate) is needed.

type Divergence

query_db_status
#

db/status.ts view source

(db: Db, namespaces?: MigrationNamespace[] | undefined): Promise<DbStatus> import {query_db_status} from '@fuzdev/fuz_app/db/status.js';

Query database status including connectivity, tables, and migration state.

Designed for CLI db:status commands. Does not modify the database.

`db`

the database instance

type Db

`namespaces?`

migration namespaces to check status for

type MigrationNamespace[] | undefined

optional

returns

Promise<DbStatus>

a snapshot of database status; connected: false with error set when the initial connectivity probe fails

throws

Error - propagated from the driver if a query fails after the

TableStatus
#

db/status.ts view source

TableStatus import type {TableStatus} from '@fuzdev/fuz_app/db/status.js';

Table info with row count.

`name`

type string

`row_count`

type number