Trestle
CP23.5 · Drilled

Restore safely

Trestle validates backup archives online and restores only while stopped, into a new data directory that does not already exist.

Preflight

Upload an archive from the Backups dashboard. Trestle verifies the archive format, path safety, database presence and schema compatibility without changing application state.

POST /admin/v1/restores/preflight

Offline restore command

systemctl --user stop trestle
# SQLite destination
trestle restore --backup ARCHIVE --data-dir ~/.local/share/trestle-restored
# PostgreSQL destination (portable archive; database must already be
# initialized at the current schema and logically empty)
trestle restore --backup ARCHIVE --provider postgres --database-url postgres://...

SQLite destination. The command refuses an existing target. It extracts only the manifest, SQLite snapshot and local file objects through a generated owner-only staging directory; rejects absolute, parent, backslash, symlink, duplicate and unexpected entries; refuses future schemas; opens and migrates the restored database; runs PRAGMA integrity_check; and only then publishes the directory atomically.

PostgreSQL destination. The destination must already exist as an initialized, logically empty Trestle database at the current schema. The archive is preflighted with the same checks; the destination migration history and complete logical emptiness are validated read-only; and the portable archive is imported transactionally. A failed restore leaves that destination semantically unchanged.

After restore

  1. Verify readiness, schema, representative records and local files.
  2. Restore provider-managed S3 objects separately when applicable.
  3. Revoke restored sessions when crossing hosts or trust boundaries.
  4. Retain the old data directory until the restored instance has been proven.
Never restore into a running instance

Do not overwrite trestle.db, mix WAL files, or combine a database from one archive with files from another.

Evidence

The CP23.5 drill completed five real database-and-file round trips. Corrupt, truncated, incomplete, future-schema, traversal and occupied-target archives all failed without publishing partial state. See Battle tested for the scoped evidence and boundaries.

Provider storage

Restore accepts both the native SQLite snapshot and the portable logical archive, staging and validating before all-or-nothing publication into an empty destination. A failed restore never mutates or partially publishes the target on either provider.