Restoring a Supabase backup into a new Supabase project

Migrating or recovering into a fresh Supabase project with pg_restore — auth schema, storage pointers, and the gotchas.

When you'd do this

Region moves, unbanning yourself from a pricing tier, splitting staging from prod, or recovering after a project became unusable. The database (including auth.users) travels in a dump; Storage files do not.

The procedure

# 1. dump the old project (direct connection, not pooler)
pg_dump "$OLD_URL" -Fc --no-owner --file=move.dump
# 2. restore into the new project
pg_restore --no-owner --no-privileges -d "$NEW_URL" \
  --exclude-schema=graphql --exclude-schema=realtime move.dump 2> errors.log
# 3. read errors.log — supabase-managed schemas will complain; your schemas must not

Gotchas

Supabase-managed schemas (auth, storage, realtime) exist in the new project with their own migrations — expect already exists noise for them; what you care about is public (and your own schemas) restoring cleanly. Storage objects need a separate copy (the storage.objects rows point at files that must be moved with the S3 API). Re-create webhooks, edge functions, and secrets by hand — they're not in the database.