How to restore a Supabase backup to a new project

Restoring a Supabase backup to a new project can mean two different things. Supabase’s native Restore to a New Project operation copies a provider-managed database recovery point. A ReviveDB restore uses an independent recovery point and also restores supported application components around that database.

That distinction matters. A database-only clone can contain Auth users and Storage metadata while the actual Storage files, Edge Functions and project configuration are still missing. ReviveDB is designed to close those gaps and to report the few remaining cutover actions explicitly.

Supabase native restore vs ReviveDB restore

Supabase’s backup documentation confirms an important boundary: database backups contain Storage metadata, not the object bytes. Its new-project restore guide lists the other project components that are not transferred by the native operation.

What ReviveDB restores automatically

Database and Auth

ReviveDB restores the logical database dump in a single transaction. It then compares the result with the recovery-point inventory, including schemas, tables, row counts, extensions, sequences, publications, replica identity, cron jobs, queues and grants. Auth users and identities are part of that database state.

Storage files and buckets

When the recovery point has Storage coverage and the target service-role key is supplied, ReviveDB recreates captured bucket settings, uploads object bytes to their original bucket names and paths, and checks the restored Storage metadata. This avoids the common failure where storage.objects rows exist but the files do not.

Edge Functions

ReviveDB checks every captured Function artifact before changing the target, deploys the matching bundles and then retrieves the deployed result to verify its metadata or source contents. A corrupt or unverifiable Function artifact fails recovery instead of producing a silent partial success.

Supported project configuration

Non-secret Auth and REST configuration is restored through allow-listed Supabase Management API fields and read back for verification. Realtime and Storage configuration follow the same path when Supabase makes those endpoints available to OAuth applications.

What still requires a manual recovery action

Some values either should not be backed up or cannot be changed safely from a backup product. ReviveDB marks these as required actions and finishes the run as “Restored, manual actions remain” instead of calling it a complete success.

• Edge Function and Vault secret values: ReviveDB records which names need attention but intentionally never copies their values. Retrieve them from your approved secret manager and set them on the target.
• Target-project API keys: a new project has new keys. Update application hosting, CI/CD and authorized clients rather than trying to preserve source-project credentials.
• External systems: DNS, OAuth-provider consoles, webhooks, payment providers and third-party allowlists live outside Supabase and must be pointed at the recovered project.
• Provider-managed infrastructure: extension binaries and available versions are controlled by Supabase. The target must be compatible with the captured declarations.
• Special queue types: partitioned and unlogged queues require manual recreation.

Restore a ReviveDB recovery point to a new Supabase project

1. Create an empty compatible target

1. Create a Supabase project in the required organization and region with a compatible PostgreSQL major version.
2. Keep it isolated from production traffic, scheduled jobs, webhooks and outbound side effects.
3. Do not add application tables or data. ReviveDB rejects a non-empty target to avoid overwriting an existing application.

2. Start the restore in ReviveDB

1. Choose a successful, verified recovery point and select restore to a new project.
2. Enter the target project ref exactly and supply its Session Pooler connection string.
3. Supply the target service-role key so Storage buckets and objects can be restored through the supported API path.

The connection string and service-role key are stored only in the encrypted restore job secret, expire after six hours and are wiped after success or terminal failure.

3. Let component verification finish

ReviveDB restores components in dependency order: database and Auth first, then Storage, Functions and supported configuration. It compares the restored database and platform artifacts with the captured recovery point before reporting success.

4. Complete the reported actions

1. Open the recovery report and set every listed Function or Vault secret from your secret manager.
2. Replace the project URL and API keys in application hosting and deployment environments.
3. Update OAuth callbacks, webhook destinations, DNS and other external integrations where necessary.
4. Recreate any special queues or unsupported provider settings listed in the report.

5. Test before cutover

• Sign in with a dedicated recovery account and refresh its session.
• Read and write representative records through the application while checking row-level security.
• Download private and public Storage objects and verify uploads to a disposable path.
• Invoke critical Edge Functions with external side effects safely disabled.
• Compare critical record counts and business totals with the chosen recovery point.
• Record the recovery point, duration, manual actions, accepted exceptions and cutover approver.

Cut over without losing the rollback path

1. Freeze source writes or define how changes after the recovery point will be reconciled.
2. Switch application environment variables and routing to the recovered project.
3. Enable jobs, webhooks and outbound integrations in a controlled order.
4. Monitor Auth, database errors, Function logs and Storage failures.
5. Keep the previous environment isolated until the agreed rollback window closes.

When should you use Supabase native recovery?

Use native PITR when the original project is healthy and you need the fastest database rollback to a precise moment. Use Supabase’s native new-project restore when its physical recovery point is the source you need and you are prepared to recover the missing application components separately. Our Supabase backups vs PITR comparison explains why many production teams keep both native PITR and an independent recovery layer.

Can you recover after a Supabase project is deleted?

Native recovery points disappear with the deleted project. Supabase states that deletion permanently removes its database, Storage objects, backups, Functions and configuration. See the official project deletion documentation. A recovery point stored independently from the project and account lifecycle is therefore the safer deletion scenario.

A restore is complete when the application works

A green database job is not enough. The recovery evidence should connect one known point in time to its verified database, Auth state, Storage bytes, Function bundles, supported configuration and end-to-end application tests. Review the Supabase restore checklist or see how ReviveDB protects the complete Supabase recovery path.