Supabase self-hosted cutover guide

A practical, source-backed sequence for moving a Supabase Cloud project to self-hosted Supabase without treating database restore as the whole launch. Use it before DNS cutover, frontend target switching, backup/PITR replacement, or asking for a second pass on one redacted packet.

Run the free trap checker Read sample report
1
Restore is one laneThe official restore flow covers database restore; Storage objects and Edge Functions need separate handling.
2
Auth needs a session planUser rows can move, but JWT signing, OAuth callbacks, and first-login behavior still need proof.
3
Backups become your jobManaged backups and PITR are platform-only; self-hosted cutover needs a tested restore path before writes move.

Fast rule

A Supabase Cloud to self-hosted migration is ready for traffic only when database restore, Storage objects, auth/session behavior, runtime keys, backup/PITR replacement, Data API grants, and rollback are all evidenced without secrets.

Do not paste private data

Use redacted notes only. Keep database URLs, passwords, JWT signing material, service-role keys, customer rows, private screenshots, payment data, full names, and private handles out of public tools, public comments, and review packets.

Cutover sequence

1

Inventory the hosted project

Record redacted schema areas, extensions, Auth providers, Storage buckets, Edge Functions, PostgREST paths, client environment names, and current rollback assumptions.

2

Stand up a disposable self-hosted stack first

Use the Docker setup path, regenerate secrets and API keys, configure public/API/site URLs, SMTP, reverse proxy, TLS, and any self-hosted services before moving production traffic.

3

Restore roles, schema, and data separately

Use the Supabase CLI dump flow for `roles.sql`, `schema.sql`, and `data.sql`, then restore into the disposable stack and compare table presence, row counts, extensions, triggers, functions, and RLS policies.

4

Replace managed backups and PITR

Do not count Supabase Cloud backups as the long-term recovery plan after writes move. Choose scheduled logical dumps, physical/base backups, WAL archiving/PITR, provider snapshots, or a managed Postgres backup tool, then record retention, restore drill result, recovery owner, and alert path.

5

Copy Storage through the S3 path

Do not treat Storage metadata as object transfer. Create or restore matching buckets, copy objects through the S3-compatible path, then test list, download, upload, overwrite, delete, and old URL rewrite behavior.

6

Prove auth and redirect behavior

Expect old platform-issued sessions to fail if signing material changes. Test password login, magic link or OTP, OAuth callback URLs, first login after migration, logout, refresh, and user-profile trigger behavior.

7

Run grant, RLS, RPC, and Storage role tests

Test no-session, anon, authenticated owner, wrong owner, wrong tenant, and service-side paths. Separate missing Data API grants from RLS policy failures before blaming the frontend.

8

Freeze, switch, monitor, and keep fallback

Freeze or queue writes, take a final backup or recovery point, switch frontend targets and DNS, monitor Auth/REST/Storage/Realtime/Functions, and keep the Cloud project fallback until the post-cutover smoke tests pass.

Minimum redacted packet

If you want the existing checker or a fixed-scope second pass to be useful, collect evidence like this without private values.

  • Restore files planned or tested: roles, schema, data, extensions, and any version mismatch notes.
  • Auth plan: migrated users, session invalidation expectation, OAuth provider callback update, and first-login tests.
  • Storage plan: buckets, object-copy method, object counts, URL rewrite, and upload/overwrite/download tests.
  • Backup/PITR plan: replacement for managed backups, scheduled backup method, WAL/PITR decision, retention, restore drill, recovery owner, and alerts.
  • Runtime plan: regenerated keys, Docker environment names, SMTP, public/API/site URLs, reverse proxy, TLS, and monitoring.
  • Access plan: explicit grants, RLS policies, RPC/function reachability, Storage object policies, and role-matrix results.
  • Cutover plan: write freeze, final backup or recovery point, DNS/frontend target switch, smoke tests, owner, and rollback trigger.
Next: paste only redacted notes into supabase-self-hosted-migration-trap-check.html.

When the $25 report makes sense

Buy only when there is one concrete migration packet and the risk is specific enough to review in 24 hours.

  • Good fit: one Supabase-backed app moving from Cloud to self-hosted this week.
  • Good fit: auth, Storage, backup/PITR, grants, RLS, RPC, runtime URL, or rollback evidence is missing.
  • Not a fit: broad architecture review, incident response, compliance certification, penetration testing, or unredacted private data.
See report scope Open scoped checkout

Source-backed problem set

Restore from platform Official database restore scope, dump flow, auth inclusion, Storage exclusion, and version mismatch guidance. Copy Storage objects Official S3-to-S3 Storage copy path, bucket preparation, rclone transfer, and object-count verification. Self-hosting Docker Official Docker setup, system requirements, generated secrets, and public URL configuration. Self-hosting responsibilities Official note that managed backups and PITR are unavailable in self-hosted Supabase, and backups/disaster recovery are your responsibility. Managed backup model Supabase platform backups and PITR explain the managed recovery model you are replacing when moving writes to self-hosted. Postgres PITR Official PostgreSQL guidance: point-in-time recovery requires a base backup plus continuous archived WAL files. Storage access control Official Storage RLS policy expectations, including extra SELECT and UPDATE needs for overwrite/upsert flows.