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, 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
Cutover needs rollbackFreeze writes, test the self-hosted stack, update URLs, verify role access, and keep a fallback path until smoke tests pass.

Fast rule

A Supabase Cloud to self-hosted migration is ready for traffic only when database restore, Storage objects, auth/session behavior, runtime keys, 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

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.

5

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.

6

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.

7

Freeze, switch, monitor, and keep fallback

Freeze or queue writes, take a final backup, 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.
  • 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, 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, 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. Storage access control Official Storage RLS policy expectations, including extra SELECT and UPDATE needs for overwrite/upsert flows.