How to restore a Supabase backup to a new project
Restoring to a new Supabase project is safer than overwriting the original. You can test the recovered application first and keep the source as a rollback path. A database restore does not recreate the whole Supabase project.
Start by checking what your backup contains. A Supabase-managed backup, a pg_dump file and an independent application backup each cover different things.
What Supabase restores to a new project
Supabase's native Restore to a New Project feature creates a database-only copy from a physical backup or PITR point. It is available for paid projects with physical backups enabled.
| Component | Native new-project restore |
|---|---|
| Database schema, data and indexes | Restored |
| Auth users and password hashes | Restored with the database |
| Storage metadata | Restored with the database |
| Storage files and bucket settings | Not copied |
| Edge Functions | Not copied |
| Auth, Realtime and project settings | Require manual reconfiguration |
| API keys and external integrations | New or manually updated |
OrioleDB Public Beta projects have scheduled backups, but Supabase does not offer PITR or Restore to a New Project for them. Check the project's Postgres type before choosing the native path. Supabase's release note lists these limits.
The easily missed part is Storage: the database contains rows describing your objects, but not the files themselves. Supabase confirms this in its database backup documentation. A restored storage.objects row cannot recreate a missing image or upload.
Prepare the target before restoring
- Choose the recovery point and write down how much recent data you are willing to lose.
- Create or select an empty target in the required region with a compatible PostgreSQL version.
- Keep scheduled jobs, webhooks and outbound messages disabled on the target.
- Keep the source project unchanged until the target has passed its checks.
- Keep Storage files and Function code with the same recovery point. Record required secret names and external dependencies. Keep their values and settings in the destination or your own secret manager.
Restore in dependency order
1. Database and Auth
Restore the database first. Auth users live in the auth schema, so a complete database recovery can retain accounts and password hashes. Review restore errors before moving on. A database that merely accepts connections is not proof that every schema was recovered.
2. Storage buckets and files
Recreate the bucket settings, then restore the actual object bytes to their original bucket names and paths. Compare file counts, sizes and checksums with the backup. Do not treat restored Storage metadata as evidence that the files exist.
3. Edge Functions and destination settings
Deploy the Function versions and their deploy metadata from the chosen recovery point. Keep the destination's Auth, SMTP, OAuth, SSO, Realtime and service settings. Supply missing secret values through the destination's normal secret manager. Recovery points record required names, never values.
4. External services
A new project has a new URL and API keys. Update application hosting, OAuth callback URLs, webhooks, DNS, payment providers and external allowlists. Keep side effects disabled until the application tests pass.
Test the recovered application
- Sign in with a dedicated recovery account and refresh its session.
- Read and write representative records while checking row-level security.
- Download private and public files and upload one disposable test object.
- Invoke important Edge Functions while email, payments and other side effects remain disabled.
- Compare key record counts and business totals with the chosen recovery point.
- Check that cron jobs, queues and database extensions behave as expected.
Only cut over when these checks pass. Freeze or reconcile writes on the source, switch the application URL and keys, then enable jobs and integrations in a controlled order. Keep the old environment isolated until the rollback window closes.
Moving a project to another account or region
If you only need a different owner, you may not need a restore at all. Supabase can transfer a project between organizations from the project's general settings. See Supabase's project transfer documentation.
A restore into a new project is the route when a transfer does not fit: a different region, an account that cannot share an organization with the old one, or a copy you want to test before switching. Follow the same order as above. Auth users move with the database, password hashes included, so they keep their passwords. They do sign in again, because the new project has its own URL and keys.
Where we fit
ReviveDB uses an independent recovery point rather than a backup tied to the source project. You select an empty Supabase target, then one guided restore covers database and Auth data, Storage files and bucket settings, and Edge Function code with deploy metadata. Destination settings and secrets stay in place. A database password is requested only when automatic access is unavailable.
Missing secret names and detected external dependencies appear as dashboard next steps. ReviveDB does not reconstruct Auth providers, SMTP, OAuth, SSO, Realtime or external services. See Supabase backup and recovery for the current coverage and access model.