Supabase migration checklist: discovery through cutover

Want an accountable migration rather than a checklist alone? WZ-IT delivers a Supabase migration from EUR 3,490 excluding VAT with an individually assessed scope.

A Supabase migration checklist prevents the project from collapsing into a PostgreSQL dump exercise. Supabase combines database, authentication, Storage, Realtime, APIs and Functions. The application has moved only when those components work together and can be operated afterwards.

This checklist supports Supabase Cloud-to-self-hosted moves, project moves and migrations of existing databases, applications or identity systems to Supabase.

Choose the source-specific path

The shared review gates remain the same, while the technical transfer differs substantially:

• Supabase Cloud to self-hosted: complete platform move including Auth, Storage and Functions
• Move a Supabase project or region: distinguish transfer, restore and a new target project
• PostgreSQL to Supabase: homogeneous database move covering roles, extensions and pooling
• AWS RDS or Aurora to Supabase: include AWS networking, roles, replication and dependencies
• Heroku Postgres to Supabase: separate the database from PaaS components
• Neon or Vercel Postgres to Supabase: map branches, serverless drivers and preview environments
• MySQL or MariaDB to Supabase: convert the data model and SQL dialect to PostgreSQL
• Microsoft SQL Server or Azure SQL to Supabase: translate T-SQL, routines, data types and identities
• Auth0 to Supabase Auth: migrate users, passwords, providers, MFA, roles and sessions
• Firebase to Supabase: remodel Firestore, Auth, Storage, Rules and Functions together
• Lovable Cloud to Supabase: separate the backend and generated application safely

1. Discovery: establish an evidence-based source state

Also capture releases and expected changes before cutover. Without a time boundary, an accurate inventory may already be stale when migration starts.

2. Target architecture and operating model

• target is Supabase Cloud, managed hosting or self-hosted
• required Cloud capabilities exist in the target or have replacements
• development, staging and production are separated
• domain, TLS, DNS and network paths are planned
• SMTP, OAuth providers and external APIs are available
• data location and access paths are documented
• scaling limits and capacity headroom are defined
• operating ownership and service levels are clear

Self-hosting does not automatically reproduce every managed Supabase Cloud capability. Complete the feature comparison before scheduling.

3. Recovery objectives and acceptance criteria

Define RPO and RTO before implementation:

• RPO is the maximum acceptable data loss.
• RTO is the maximum acceptable recovery duration.

They determine backup frequency, replication, maintenance windows and rollback. Make acceptance measurable:

• row counts for critical tables reconcile
• all Storage objects transfer and representative files open
• every relevant Auth provider passes login and logout
• unauthorised roles fail RLS negative tests
• critical user journeys work against the new backend
• backup, monitoring and alerting are active

4. Prepare the database

• complete source backup exists
• versions and extensions are target-compatible
• roles, ownership and grants are captured
• functions and triggers can load in dependency order
• large tables and long imports are identified
• sequences and identities can be verified
• business constraints and relations can be tested
• changes between first import and cutover are addressed

A clean import log is not proof of consistency. Compare critical queries, foreign keys, sequences and business totals.

5. Plan authentication

• users, identities and providers are inventoried
• password hashes or reset process are understood
• JWT secrets and session impact are assessed
• custom claims and roles are mapped
• OAuth redirects for new domains are prepared
• SMTP, sender and email templates are tested
• MFA and recovery paths are included
• representative accounts exist for every login type

A forced new login may be acceptable. It must not be discovered after cutover.

6. Move Storage separately

• bucket configuration and visibility are documented
• object count, volume and largest objects are known
• download and upload process is tested
• content types and metadata remain intact
• Storage RLS is configured in the target
• public, private and signed URLs are tested
• checksums or representative samples are planned
• the application uses the new object paths

Supabase explicitly documents that database backups do not contain the actual Storage objects.

7. Functions, Realtime and secrets

• Function code is versioned
• all secrets are known and securely transferred or rotated
• external webhooks and callback URLs are updated
• runtime and dependencies work in the target
• Realtime channels and replication are configured
• scheduled jobs and triggers are captured
• CORS and allowed origins are restricted
• errors, logs and timeouts are observable

8. RLS and access controls

• RLS is enabled on exposed tables
• grants and policies work together
• anon, authenticated and server roles are separated
• tenant and owner boundaries are tested
• INSERT, SELECT, UPDATE and DELETE are tested independently
• views, functions and Storage are included
• service keys never reach the browser
• negative tests are automated or documented

9. Application and integrations

• new Supabase URL and publishable keys are configured
• server-side keys remain separate and protected
• frontend and backend are rebuilt or redeployed
• API, Function and Storage endpoints are updated
• OAuth and email links use the new domain
• error handling and token refresh are tested
• monitoring or analytics use the right endpoints
• old clients and versions are accounted for

10. Rehearsal

Run the rehearsal with a current source and the intended target architecture. Measure:

• duration of every export and import
• manual steps and waiting time
• warnings and deviations
• actual downtime
• technical and business test duration
• required access and decision makers

Turn the result into an executable runbook containing time, owner, input, expected output and rollback criterion.

11. Cutover

• stakeholders and users are informed
• changes and releases are frozen
• source is backed up
• write boundary or maintenance mode is active
• final data and Storage reconciliation is complete
• target is published and application switched
• smoke and business tests pass
• go/no-go is recorded
• source remains available for the rollback window

12. Operations after migration

• monitoring and alert paths are active
• database and Storage backups run
• recovery is documented and scheduled for testing
• patch and upgrade process is defined
• capacity and growth are observed
• secrets and temporary access are rotated
• operating documentation is handed over
• old systems are retired only after acceptance

Sources

• Supabase: transfer Cloud to self-hosted
• Supabase: restore Platform to self-hosted
• Supabase: database backups
• Supabase: update self-hosted deployments
• Supabase: Row Level Security