> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Status

Last updated 29 October 2026

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

`status()` of an [UrsulaDatabase](https://tonbo.dev/docs/reference/nodejs/database.md) 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](https://tonbo.dev/docs/databases/troubleshooting.md).

```text
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()](https://tonbo.dev/docs/reference/nodejs/open.md#provisional)); `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](https://github.com/tonbo-io/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](https://tonbo.dev/docs/reference/nodejs/open.md#option-max-pending-bytes). |
| `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](#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](https://tonbo.dev/docs/databases/how-it-works.md#move)). |
| `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](https://tonbo.dev/docs/reference/nodejs/errors.md#ursula-write-refused-error)). |
| `salvage` | `UrsulaSalvage[]` | Local caches of this stream moved aside, oldest first. See [UrsulaSalvage](#ursula-salvage). |
| `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](https://tonbo.dev/docs/reference/nodejs/errors.md#ursula-reset-error)). |

## 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](https://tonbo.dev/docs/databases/pricing.md#zero-balance)). |
| `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](https://tonbo.dev/docs/reference/nodejs/environment.md#extension)). |
| `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](https://tonbo.dev/docs/databases/backups.md#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. |