SQLite Backup and Restore

Create consistent snapshots of a managed local Federation and explicitly restore its stopped database.

fed backup and fed restore support registered local SQLite deployments with an independent release and persisted runtime configuration. They do not operate on remote PostgreSQL, Workers databases, unregistered directories, or database paths inferred from source.

Create an online backup

fed backup --id fed_example
fed backup --name example

The service may remain running. The CLI uses SQLite's online backup API, including committed WAL data, rather than copying a live main database file. It does not stop or restart the service.

Targets follow the one-operation selection rules: --id and --name are mutually exclusive exact matches. Omitting them in an interactive terminal opens a list; non-interactive calls require a target. Duplicate names require selection; scripts should use a unique ID.

The database is identified only by the deployment's runtime.env.json: DATABASE_PATH must be an absolute path to an existing regular file and match the file: value in DOWNCITY_FEDERATION_DATABASE_URL. The CLI neither creates a missing source database nor searches the current directory for one.

Completed snapshots are stored at:

~/.downcity/federation/backups/<fed_id>/<backup_id>/database.sqlite
~/.downcity/federation/backups/<fed_id>/<backup_id>/backup.json

backup.json is written after the snapshot is complete, converted to a standalone database needing no WAL/SHM files, and passes PRAGMA integrity_check. It records the owning Fed, creation time, application version, release ID, byte size, and SHA-256 digest. The CLI syncs the database, metadata, and directories to disk before reporting backup success. Temporary or incomplete directories are not accepted as completed backups.

Directories use 0700; database and metadata files use 0600. Backups can contain private user data, administrator and user sessions, service configuration, and credentials. Never commit them to Git or include them in a release. The digest detects file changes; it is neither encryption nor a digital signature. Use appropriate encrypted storage for off-machine copies.

Preview and restore

Explicitly stop the target service before restore preflight:

fed stop --id fed_example
fed restore --id fed_example --path /absolute/path/to/backup_id --dry-run

--path accepts a completed backup directory or its database.sqlite. The sibling backup.json is required, must not exceed 64 KiB, and must contain valid JSON. The directory name must match its backup ID. A backup can be restored only to its owning Fed. The digest, size, and SQLite integrity are checked again; unknown formats and snapshots with -wal, -shm, or -journal sidecars are rejected. The selected backup directory, database file, and metadata file must not themselves be symbolic links. The checks do not cover every parent directory, so use backups in trusted locations.

--dry-run verifies the backup, database location, and manager stop facts without creating a safety backup, checkpointing the current database, replacing data, or changing service state. It does not open the current database to check SQLite integrity or connection contention. Passing preflight does not guarantee that the actual restore will succeed.

Perform a restore:

# Save the current database, display the plan, then request confirmation
fed restore --id fed_example --path /absolute/path/to/backup_id

# Explicit replacement authorization for non-interactive use
fed restore --name example --path /absolute/path/to/backup_id --yes

Preflight requires more than active: false. On macOS, the launchd job must be unloaded, its login startup definition absent, and the owned stopped marker present. On Linux, the systemd user service must be inactive, have no main PID, be disabled, have no default-target startup link, and have its stopped marker. Temporary exits, pending automatic recovery, or unverifiable status fail the check. The command does not stop the service for you.

Restore sequence

  1. Acquire the Fed operation lock and validate the target and complete backup.
  2. Create a consistent safety backup of the current database with purpose: before_restore.
  3. Display the replacement path, backup version, and safety backup location for explicit confirmation.
  4. Recheck stop facts, backup integrity, and whether the current database changed during confirmation.
  5. Prepare and verify the replacement in the current database's directory. Use SQLite checkpointing to settle WAL state, refusing databases held by other connections.
  6. Atomically replace the main database and save its stopped status. Leave the service stopped.

Cancelling confirmation leaves the current database unreplaced and retains the safety backup. The read-only SQLite connection used for the safety backup may create empty WAL/SHM sidecars that remain after cancellation. Their presence does not mean the main database was replaced. Incomplete or modified snapshots, detected external writes during confirmation, and database contention that blocks validation prevent replacement. After confirmation, replacement preparation may checkpoint the current database and switch it to DELETE journal mode. A later failure before main-file replacement does not mean the files and journal state are unchanged. Errors from the replacement stage report whether replacement completed and where the safety backup is stored. Cleanup attempts every temporary restore file and its sidecars. If cleanup fails, the thrown AggregateError message still states whether the database was replaced and includes the safety backup path. Its errors array retains each cleanup error and, if restoration also failed, the original restore error. Inspect the database, safety backup, and manager stop facts before deciding what to do next. Do not retry blindly.

The Fed lock excludes concurrent deploy, restart, stop, and clean commands for this deployment. It does not control external processes bypassing Fed; close other direct database tools during restoration.

After restoration

Restoration replaces the entire database, including database-stored accounts, sessions, business configuration, billing, and job facts. It does not switch the application release, current.json, persisted runtime.env.json, logs, or the City's selected connection.

The database schema must be compatible with the installed application. The CLI displays versions but does not guarantee schema compatibility across versions, roll back the application, or automatically migrate data. Decide explicitly whether to run fed restart --id fed_example after inspection. Existing deployment recovery guards remain in effect.

Database-stored administrator sessions may change, so the CLI's saved administrator Session may require a new login. User Tokens retained by City are valid only according to the restored database facts. Credential validity before restoration is not a guarantee afterward.

Backups and safety backups are neither scheduled nor cleaned automatically. fed clean manages releases only; it does not delete backups, databases, configuration, or logs. Establish a separate retention and off-machine storage policy.