Status

Last updated 29 October 2026

Every field of the object db.status() returns, UrsulaStatus, and what each means.

status() of an UrsulaDatabase is synchronous and reads only local state. Its fields are snake_case, the same JSON the extension’s ursula_status returns to every host. What to do about a value is on Troubleshooting.

status(): UrsulaStatus

UrsulaStatus

Field	Type	What it means
`name`	`string`	The stream’s path, such as `/acme/notes`.
`path`	`string`	The local database file the extension bound.
`state`	`string`	`live`; `provisional` while an open that found the stream unreachable serves the trusted cache with its claim deferred (see open()); `retiring` once its last connection closed and replication drains; `retired`; or `reset`.
`role`	`string`	`owner`, or `reader` for a `readOnly` open’s own reader cache, which claims nothing. A read-only connection on the binding its process owns reports the owner’s status.
`closed`	`boolean`	Whether the stream was closed when the open read it. Only a reader opens a closed stream.
`epoch`	`number \| null`	The epoch this owner claimed, `null` before its claim is acknowledged and for a reader.
`cluster_id`	`string`	The id of the Ursula deployment that holds the stream.
`incarnation`	`string`	The stream's incarnation, which changes when the stream's history changes, such as a restore or a recreate.
`lineage`	`string`	The local cache's lineage: a cache built anew has a new one.
`commits.logged`	`number`	The position of the last commit logged locally.
`commits.confirmed`	`number`	The position of the last commit SQLite published.
`commits.acknowledged`	`number`	Every commit up to this position is in the stream.
`commits.pending`	`number`	How many logged commits the stream has not acknowledged yet.
`commits.pending_bytes`	`number`	Their compressed size, which writes may not take past maxPendingBytes.
`replication.state`	`string`	`activating` while the claim goes out, `streaming` once it applied, `reset`, `refused` (the claim lost to racing claimants), `stopped`, or `none` for a reader.
`replication.condition`	`string \| null`	Why requests wait, or `null`. See Conditions.
`attach.local`	`string`	Where the open got the local database: `resumed` (a trusted local cache), `rekeyed` (a trusted cache kept across a history change that inherits it), `built` (from the stream), `salvaged` (built after moving the cache into `salvage/`), or `caught_up` (a reader cache read to the stream’s tail).
`attach.snapshot_offset`	`number \| null`	For `built` and `salvaged`: the snapshot it built from, or `null` from the stream’s start.
`snapshot.offset`	`number \| null`	The stream offset of the latest snapshot this binding published, `null` before its first. A new cache builds from a snapshot and the log after it (see When the program moves).
`snapshot.age_ms`	`number \| null`	How long ago it published that snapshot, `null` before its first.
`snapshot.failures`	`number`	Failed attempts since the last that published.
`snapshot.error`	`string \| null`	Why the latest attempt failed, or why snapshots stopped for good; `null` when neither.
`snapshot.log_bytes`	`number`	Frame bytes acknowledged since the latest snapshot.
`snapshot.due_bytes`	`number`	The log_bytes past which a snapshot is due.
`refused`	`object \| null`	The last write refused with nothing committed: `kind`, `action`, `class`, which is `write_refused` (since 0.11.2), and `message` (see UrsulaWriteRefusedError).
`salvage`	`UrsulaSalvage[]`	Local caches of this stream moved aside, oldest first. See UrsulaSalvage.
`reset`	`object \| null`	`null` until the database is reset, then its `kind`, `action`, and since 0.11.2 its `class`, which is `reset`, and the `message` that says what happened and what to do (see UrsulaResetError).

Conditions

replication.condition says why requests to the stream wait. Commits continue locally meanwhile, until maxPendingBytes is reached. retrying is a request that got no definite answer and goes again after a backoff; every other condition blocks, and the request goes again every 30 seconds until the cause is gone.

Condition	What it means
`retrying`	No definite answer, such as a network failure.
`unauthorized`	The stream answered 401: the token is missing, expired or revoked.
`payment_required`	The stream answered 402 (see When the balance runs out).
`forbidden`	The stream answered 403, such as for an account whose access was revoked.
`request_too_large`	A request was refused as too large (see URSULA_VFS_MAX_REQUEST_BYTES).
`redirected`	The stream answered with a redirect, which is never followed.
`wrong_cluster`	The server is another deployment than the one the cache was built on.
`no_server_identity`	An answer without `Ursula-Protocol` and `Ursula-Cluster-Id`, such as a proxy’s.
`protocol_mismatch`	A server of another release line.
`rejected`	Another status the extension does not retry.

UrsulaSalvage

An entry of salvage: a local cache moved aside, never read or deleted by the extension. Its dir holds a plain SQLite database db, its log and a manifest.json (see Salvage).

Field	Type	What it means
`dir`	`string`	Where it was moved.
`reason`	`string`	`history_changed` (a history change of the stream that does not keep it), `replaced` (a db file that was not the cache’s own), or `recreated` (the stream created again over it with `recreate`).
`time`	`string`	When it was moved aside, RFC 3339 in UTC.
`incarnation`	`string \| null`	The stream incarnation the cache was built under, `null` for a replaced one.
`stream_incarnation`	`string \| null`	The stream's incarnation when it was moved aside.
`acknowledged_position`	`number \| null`	Every commit up to here was in the stream under `incarnation`; `null` for a replaced one.
`unacknowledged`	`number \| null`	How many of its commits came after that, which the stream may never have held.
`plain`	`boolean`	Whether `db` opens as a plain SQLite database.