Restore overview

Why the CLI, not the dashboard

Restoration is a destructive operation against a database you control. Walwarden cannot hold the credentials needed to write to your target database without becoming a high-value attack target and requiring you to trust walwarden with access you cannot audit.

The trust boundary is enforced by architecture, not policy:

• The dashboard issues a short-lived, single-use HMAC token. The token encodes which backup artifact to restore, which mode to use, and an expiration.
• The CLI runs on a machine you control. It uses the token to claim the restore job, retrieve a presigned S3 URL for the artifact, download the bytes, verify the manifest checksum, and pipe the bytes to pg_restore on your machine.
• Your target DSN never leaves your machine. The CLI accepts it as a flag or environment variable; it is not sent to walwarden's server.
• The dump bytes flow from S3 to your machine to pg_restore. Walwarden's server never sees them.
• Every state transition (download started, checksum verified, restore completed) is posted back to walwarden for the audit chain, but the payload contains no data content — only state labels and timestamps.

High-level flow

1. You click "Restore from this backup" on the backup detail in the dashboard.
2. The dashboard issues a token and renders the one-liner command.
3. You copy the one-liner, replace the target DSN placeholder with your actual DSN, and run it in a terminal on a machine that can reach the target database.
4. The CLI claims the restore job, downloads the dump from S3 via presigned URL, verifies the SHA256 manifest checksum, and pipes bytes to pg_restore.
5. State transitions stream to the dashboard in real time via the audit event channel.
6. The CLI exits 0 on success. The token is invalidated.

What you need on the restore machine

• Node 20+
• pg_restore matching the major version of the source database (see Install the CLI)
• Network access to the target Postgres (can be localhost, a VPN, a bastion — anywhere psql would work)
• No AWS credentials required — the presigned URL handles S3 authentication

Continue

• Restore walkthrough — step-by-step with the actual commands
• Restore modes — new_database vs in_place, when to use each
• Troubleshooting — common failures and their remedies