Description
Local Backup and Restore protects a machine-hosted Dots workspace with real PostgreSQL snapshots. A backup can be requested from a running daemon or taken offline using the bundled pg_dump tooling. Each backup includes a manifest and database facts used to validate integrity before it is accepted. Operators can list stable backup identifiers, select the newest pre-migration recovery point, and rotate older snapshots under a retention policy.
Restore runs against an offline throwaway PostgreSQL server, validates the recovered database, and swaps the restored data directory into place only after checks pass. The daemon must release the live data directory first, and concurrent offline operations are locked. A failed validation leaves the active data untouched instead of turning a damaged archive into the new source of truth.
Selling Points
- Protects local-first work with database-native snapshots rather than brittle directory copies.
- Validates restored contents before activation, reducing the chance that a corrupt backup replaces working data.
- Creates automatic pre-migration recovery points and periodic backups around the moments data is most vulnerable.
- Lists and resolves human-usable backup identifiers while retaining exact manifests for diagnosis.
- Uses bundled PostgreSQL tools, so recovery does not depend on a separately installed database client.
User Story
Before a risky upgrade, an operator runs dots local backup and sees the resulting backup identifier. If the upgrade later proves unsuitable, they stop the daemon and run dots local restore <id>. Dots restores into an isolated server, verifies the database facts, and atomically activates the recovered data. The operator returns to the previous workspace instead of rebuilding it by hand.
Extension Surface
This feature is automatable. packages/local-runtime/src/client/operability.ts exposes the CLI-facing backup and restore functions, while packages/local-runtime/src/db/snapshot.ts implements the offline workflow. Scripts can create, enumerate, and restore backups end to end. Backup formats, validation rules, and retention machinery are core contracts rather than plugin extension points.
Capabilities & Limits
- Takes snapshots from a running daemon or a stopped local data directory.
- Validates manifests, schema/database facts, and restored contents before the directory swap.
- Supports backup listing, stable aliases, retention rotation, and automatic maintenance.
- Limit: restore requires exclusive ownership of the local data directory and refuses while a daemon still holds it.
- Limit: packaged builds must include the offline engine and PostgreSQL tools; missing payloads produce a named refusal.
Implementation Map
packages/local-runtime/src/client/operability.tspackages/local-runtime/src/db/snapshot.tspackages/local-runtime/src/db/backup-listing.tspackages/local-runtime/src/db/backup-maintenance.tspackages/local-runtime/src/db/postgres-tools.tspg_dumppg_restore