Skip to content
HostwrightHostwright

State store

Hostwright’s local state store is SQLite, using the system SQLite3 library — no external dependencies. It persists desired-state snapshots, observed runtime snapshots, the event ledger, operation records, ownership records, health results, restart policy state, restart recovery records, and operation recovery groups with step-level checkpoints.

An explicit SQLite state database feeding a ledger of desired, observed, events, operations, ownership, health, and recovery records, read back by the read-only events, recovery, and diagnostics commands.

Explicit paths only

Section titled “Explicit paths only”

Hostwright never chooses a database path for you. There is no default under the repository, ~/Library/Application Support, XDG paths, or any global location. Every stateful command takes --state-db <path>:

Terminal window
hostwright status --state-db /tmp/hostwright.sqlite
hostwright events --state-db /tmp/hostwright.sqlite

Write-path commands (status, logs --state-db, apply, cleanup, hostwrightd --foreground) can run explicit migrations before writing. Read-only commands (events, recovery, diagnostics) validate the already-applied schema and fail rather than creating or migrating a database as a side effect.

Migration continuity

Section titled “Migration continuity”

Migrations are explicit and checksummed:

  • Schema version 6 is the latest supported version. A database migrated by a newer Hostwright release fails closed with an incompatible-schema error; Hostwright does not downgrade or convert.
  • Each migration records a checksum in schema_migrations. A known version with an unexpected checksum fails before any application reads or writes.
  • Applied migration history must be a contiguous prefix starting at version 1. A database recording a later migration while omitting an earlier one fails closed — Hostwright does not infer, replay, or silently repair out-of-order history. A valid older contiguous prefix remains eligible for explicit forward migration.

Schema version 6 added exact observed resource identifiers, observed network metadata, and ownership identity versions; legacy rows are backfilled as identity version 1, new labeled resources are written as version 2. See Runtime adapter — identity and ownership.

What is (and is not) stored

Section titled “What is (and is not) stored”

Normalized columns hold identifiers, project and service names, timestamps, lifecycle states, operation status, event severity, restart status, recovery checkpoints, lock leases, and hashes. JSON blobs hold ports, networks, mounts, environment snapshots, event and operation payloads, and recovery metadata — all redacted before persistence.

Concurrency

Section titled “Concurrency”

The contract is single-writer: one CLI command or daemon may write a state database at a time. Hostwright uses SQLite full-mutex mode, a bounded busy timeout, and BEGIN IMMEDIATE transactions. If another process holds a write lock beyond the timeout, Hostwright reports a locked database instead of waiting indefinitely. Operation-group acquisition is atomic across concurrent stores — exactly one winner.

No transaction performs runtime mutation. Apply and cleanup write intent first, leave the transaction, call the RuntimeAdapter, then record success or failure.

Backup and restore are cold operations

Section titled “Backup and restore are cold operations”
  1. Stop any Hostwright command or daemon using the database.
  2. Copy the explicit SQLite file plus sidecars (*-wal, *-shm) if present.
  3. To restore: move the existing database aside (never overwrite), copy the backup into place, and verify with a safe read such as hostwright events --state-db <path>.

There are no online backup, restore, or repair commands, and no production durability guarantee. Corruption recovery is manual: keep the file, restore from a cold backup, or start a new explicit path. Hostwright never invents ownership records or erases state automatically.