Migrate Supabase Cloud to self-hosted: complete process

Avoid treating the move as a one-off database import. WZ-IT delivers a Supabase migration from €3,490 with assessment, rehearsal, cutover and a documented rollback checkpoint.

A Supabase Cloud to self-hosted migration consists of several connected moves. PostgreSQL is the core, but Auth, Storage, Functions, secrets, Realtime and application configuration all need to point to the target.

The official Supabase guide explains the database transfer and explicitly states that storage objects and Edge Functions are not moved by that process. A production application therefore needs a broader runbook.

1. Inventory the source

Collect at least:

• PostgreSQL version, database size and write rate
• active extensions and custom roles
• schemas, views, functions, triggers and cron jobs
• auth providers, MFA, SMTP and redirect URLs
• user count and active sessions
• storage buckets, object count, total volume and policies
• Edge Functions, secrets, webhooks and external APIs
• Realtime, Broadcast and Presence usage
• pooling, direct database connections and domains
• frontends, mobile apps, servers and automations
• required RPO, RTO and maintenance window

The assessment also needs a Cloud-to-self-hosted feature matrix. Branching, managed backups/PITR and other platform capabilities are not automatically available on the target.

2. Prepare a compatible target

The target stack should be fully operational before importing data:

• version-tracked self-hosted Supabase stack
• compatible PostgreSQL version and extensions
• TLS, firewall and protected Studio access
• SMTP and auth providers
• storage backend with adequate capacity
• backup for PostgreSQL, Storage, configuration and Functions
• monitoring, logs and alerts
• domains, pooling and network access

Supabase notes that Cloud and self-hosted deployments may use different PostgreSQL or service versions. A rehearsal identifies incompatible settings, tables or extensions before the production window.

3. Export roles, schema and data

The official restore guide creates three exports:

supabase db dump --db-url "$DATABASE_URL" -f roles.sql --role-only
supabase db dump --db-url "$DATABASE_URL" -f schema.sql
supabase db dump --db-url "$DATABASE_URL" -f data.sql --use-copy --data-only

The Supabase CLI runs pg_dump internally but filters reserved roles and internal schemas for the platform. An unfiltered direct dump can fail during restore because of ownership or reserved roles.

Custom login roles need new passwords after restore because passwords are not included in the dump.

4. Run a test restore

Restore roles, schema and data in the required order. A successful psql exit code is not sufficient. Validate:

• table and row counts
• constraints, indexes and sequences
• views, triggers and database functions
• extensions and versions
• owners and grants
• RLS policies
• critical queries and performance
• application migration history

Record every difference. The rehearsal also provides a realistic transfer duration for the maintenance window.

5. Handle Auth separately

Auth data partly lives in PostgreSQL and may move with the data. The environment still needs confirmed configuration:

• Site URL and allowed redirects
• OAuth providers and callback URLs
• SMTP, sender and templates
• JWT keys and token validity
• anonymous and public sign-up
• MFA and CAPTCHA

The official documentation notes that different JWT secrets invalidate existing tokens. Users then need to sign in again. OAuth configuration in Google, Apple, GitHub or other providers must point to the new hostname.

6. Transfer Storage objects

A database dump transfers tables and Storage metadata, not the file content. Storage requires its own process:

1. Inventory buckets, policies and metadata.
2. Read every object from the source.
3. Transfer files to the target backend.
4. Compare paths, size, checksums and object counts.
5. Test public and signed access paths.

For large buckets, Storage transfer can take longer than the database move. Incremental transfer then requires a separately designed strategy.

7. Redeploy Functions, secrets and integrations

Treat Edge Functions as source code and deployment artefacts. Move:

• function code and imports
• environment variables and secrets
• webhook endpoints
• cron or queue triggers
• JWT verification and service-role usage
• external API access

Self-hosted Functions run on the target Deno runtime rather than the automatically global Cloud edge network. Test latency, scaling and timeouts for the new operating model.

8. Test the application against the target

Connect a staging deployment to the target before cutover. Acceptance should include:

• registration, login, logout and password reset
• OAuth and email flows
• create, read, update and delete per role
• negative RLS tests between users and tenants
• uploads, downloads and signed Storage URLs
• Realtime connections
• Functions and webhooks
• direct server and pooled connections

These tests show whether the backend works as a system rather than only as a restored database.

9. Cutover and rollback

Derive the final sequence from the rehearsal:

1. Activate a change freeze or controlled write pause.
2. Perform the final database and Storage transfer.
3. Verify quantities and critical records.
4. Switch secrets, URLs and application deployments.
5. Run smoke tests and business acceptance.
6. Keep the source unchanged for the agreed rollback window.

Rollback is only credible when new writes after the switch have a defined treatment. Complex applications may require incremental synchronisation, which increases the scope and must be priced individually.

Operations begin after migration

Self-hosting changes responsibility. Activate these controls immediately:

• monitoring and alerting
• database and Storage backups
• documented restore
• update and patch process
• capacity controls
• incident ownership
• recurring RLS and configuration review

WZ-IT can operate these controls as a managed Supabase service after migration.

Sources

• Supabase: restore a Platform project to self-hosted
• Supabase: transfer from Cloud to self-hosted
• Supabase: self-hosted Functions
• Supabase: database backups