Backup and recovery
Distinguish database snapshots, configuration bundles and OS-stored secrets.
On this page
Workflow
A database backup contains configuration and history, not OS credential-store secret values. Restore into a new directory, re-enter secrets and approve again. Configuration import creates new resource IDs; a full snapshot may retain old IDs and reference the same-user credential-store entries.
Boundary and checks
0.3.1 uses schema 25 and bundle format 2, but compatibility with older data is not guaranteed. Inspect a trusted backup offline and preserve the original; never publish a full diagnostic bundle or database in an issue.
Three files serve different purposes
| File | What it contains | After migration or recovery |
|---|---|---|
| Configuration JSON | Resources, connection settings, templates and ordinary parameters; no secrets or history | Append import creates new identifiers; re-enter secrets and approve again |
| Consistent SQLite backup | Configuration, approvals, history, filtered output, PIN verification material and encrypted diagnostics; no OS credential-store secret values | Restore only into a new directory; configure secrets and authorization again |
| Compact diagnostics | Version, state counts and stable error-code summary | Troubleshooting aid, not a configuration or data backup |
“No secret values” does not make a file public. Ordinary fields may contain private addresses, commands, business parameters and results. Do not attach configuration, SQLite data or unreviewed detailed diagnostics to a public issue.
Move configuration
Export JSON from Settings → Data maintenance. On the destination, inspect the import and review counts and relationships before confirming it. Import appends rather than replacing same-named resources and does not migrate authorizations or OS credentials. Check executable paths, private CAs, repository directories and file paths on the new machine; cross-platform paths are not converted automatically. If confirmation loses connectivity, retry the same file to retrieve its original receipt.
Backup, inspect and restore
Use “Download SQLite backup” for a consistent snapshot including committed WAL changes; do not copy only the live main database file. Inspect through the page or secretbridge --inspect-backup ABSOLUTE_FILE_PATH. Version 0.3.1 accepts schema 25 and configuration format 2; old formats are not promised compatible.
For a full restore, stop the broker and bridge, set SECRETBRIDGE_DATA_DIR to a not-yet-existing absolute directory, then run --restore-backup. Configuration and history remain, but credentials are marked unconfigured, unfinished runs are interrupted, and pending or approved grants are revoked. Re-enter secrets and request new approval. Under the same OS account, retained UUIDs can still refer to original credential-store entries; use configuration import when independent copies are needed.
Corresponding product documentation · Report a documentation issue