Knowledge base · Restores

Restoring a backup into a new project

How a one-click restore works, why the target must be empty, what to do about Postgres versions and Storage, and what the report tells you.

Restores write your backup into a database you designate. VaultKeep never restores over the project it backed up: the target must be empty, on purpose.

Before you start

1. Create a new, empty Supabase project (or any Postgres database you control). Its Postgres major version must be the same as, or newer than, the version the backup came from; the version is shown on the backup.
2. Copy its connection string (direct or session pooler, port 5432).
3. For a Storage restore, you also need the new project's ref and S3 access keys, so buckets and files can be recreated.

Steps

1. Open the original project → Backups, pick the backup, click Restore.
2. Paste the target connection string (and ref + S3 keys for Storage).
3. Type the project name to confirm. This is the two-step confirmation; there is no way to skip it.
4. Watch progress under Restores. You are emailed when it finishes.

The target credentials are used once and destroyed as soon as the restore ends.

What happens

• Preflight: the runner connects to the target and counts user tables. If there are any, the restore aborts with "the destination already contains N user tables" and nothing is written. This is the control that makes restoring over production impossible.
• Integrity: the artifact's hashes are checked before anything is restored.
• Database: a full pg_restore (--no-owner, parallel jobs), skipping Supabase-managed schemas such as auth, storage and extensions, which the new project already provides.
• Storage: buckets are created with the same names, and every object is streamed back decrypted with the key recorded for it in the manifest.
• Report: the same checks as a verification run against the restored database (table and row counts versus the manifest), plus the count of restored objects for Storage. The report is stored with the restore and shown in the app.

After the restore

• Re-point your application at the new project, or migrate settings (Auth providers, Edge Functions, secrets) that live outside the database and Storage.
• Rows in auth.users are part of the auth schema and are not restored by default, because the new project manages that schema. If you need users migrated, export them with supabase db dump --data-only --schema auth from the original project while it still exists.
• Check a few signed Storage URLs and your most important tables before announcing it done.

If a restore fails, the target is left as it is; fix the cause shown in the report and start a new restore.

Still stuck? Email support@vaultkeep.dev with your project name (never your connection string) and we'll take a look.