Restore a Backup

Restore the latest backup or recover to a specific point in time.

Always restore to a temporary file first

borela-agent restore requires -output. Point it at a new temporary path, inspect the restored database, then decide whether to copy it over production.

Do not restore directly over the live SQLite file while the app is running. Stop the app, move the old file aside, then promote the restored file only after basic checks pass.

borela-agent restore -project app -output /tmp/app-restored.db
sqlite3 /tmp/app-restored.db 'PRAGMA integrity_check;'

Scenario: the server or disk disappeared

If the machine is gone, restore the latest available state. Omit -timestamp. Borela asks Litestream for the most recent replicated database it can assemble from the retained backup history.

Run this on a replacement machine with borela-agent installed and configured for the same project and storage credentials.

borela-agent restore -project app -output /tmp/app-restored.db

Scenario: a bad deploy, delete, or migration

If the app is still running but the data is wrong, choose the moment just before the mistake. Use a UTC RFC3339 timestamp such as 2026-04-25T18:00:00Z.

Point-in-time restore recovers to the latest replicated state at or before the requested time, as long as the needed Litestream history is still inside the retained window.

borela-agent restore -project app -timestamp 2026-04-25T18:00:00Z -output /tmp/app-before-migration.db

Find a timestamp

Start with the dashboard backup history if you just need the last known backup timestamp. For a precise incident, use your deploy log, application log, audit trail, or the time you ran the destructive command.

borela-agent snapshots prints replica files with UTC timestamps and a SAFE_TIMESTAMP_UTC column. If you are choosing directly from that table, use SAFE_TIMESTAMP_UTC so the listed file is included in the restore plan.

borela-agent snapshots -project app
borela-agent restore -project app -timestamp 2026-04-25T18:00:01Z -output /tmp/app-restored.db

Retention and granularity

Borela configures the agent for seven days of Litestream snapshot retention. In healthy operation, that means point-in-time recovery is available within the retained seven-day window.

Granularity changes as Litestream compacts older files. Recent history is finer grained; older history is compacted into larger intervals. Treat the timestamp as the target recovery time, not a promise that every wall-clock second has a separate snapshot file.

Promote the restored database

After restore, run integrity_check and any application-level smoke checks that matter. Then stop the app, copy the current production database somewhere safe, move the restored file into place, fix ownership and permissions, and start the app again.

Keep the pre-restore production file until you have confirmed the app is healthy. Even a corrupted or wrong database can be useful evidence during an incident.

sudo systemctl stop myapp
sudo cp /srv/myapp/app.db /srv/myapp/app.db.before-restore
sudo cp /tmp/app-restored.db /srv/myapp/app.db
sudo chown deploy:deploy /srv/myapp/app.db
sudo systemctl start myapp