Migration field guide
Firebase to Supabase: data, auth and cutover
Treat authentication, database data, storage and application behaviour as separate migration workstreams.
Edited by Clinton Feyisitan · Documentation checked
Review scope: Official documentation and field mapping reviewed. The steps below are a proposed validation procedure, not a completed native migration or a measured completion-time claim.
What the documented route supports
Supabase publishes separate Firebase Auth, Firestore and Storage migration guides. Firestore documents require a relational mapping; its utility supports flattening nested data and preserving Firestore IDs. The Auth guide includes password-hash parameters and describes a separate approach for verifying existing Firebase passwords. Copying user rows alone is not proof that existing sign-ins work.
Map before importing
| Source | Destination | Check |
|---|---|---|
| Firestore document ID | Stable primary/reference key | Check relationships after flattening nested documents. |
| Firebase user ID | Auth / application identity map | Verify ownership links as well as account counts. |
| Security rules | Postgres / storage authorization | Test denied access explicitly; schemas do not migrate rules. |
| Functions, triggers and jobs | Reimplemented runtime | Compare side effects, retry behaviour and event ordering. |
A controlled migration
- Back up the source and list collections, indexes, rules, authentication providers, storage objects, functions and background jobs. Define a write-freeze or reconciliation strategy.
- Design destination tables, keys and relationships for one collection. Follow the official Firestore utility in an isolated project; keep document IDs for reconciliation.
- Plan Auth separately, including password migration, OAuth callbacks, email flows and user-ID references. Keep service credentials outside source control.
- Rebuild authorization, storage access and functions, then point a non-production application at the destination. Cut over only after a full scoped rehearsal and a recoverable data snapshot.
Acceptance checks
Record the result and evidence for each check. Stop the cutover if a required check fails.
- Reconcile counts, nulls, timestamps, nested arrays and key relationships.
- Test an existing login, password reset, OAuth callback and unauthorized read.
- Test duplicate events and recovery after a partially failed write.
Budget for overlapping plans, required features, seats, storage or usage, and the time to reconcile exceptions. Check the current provider quote; this guide does not reuse historical subscription prices.
Keep a way back
Retain Firebase and a cutover log. If writes have reached both databases, reconcile them before switching back; changing a connection string alone can lose data. Restore from a verified snapshot only under a documented recovery plan.
Official sources
Source availability and account UI can change. Native account execution remains untested in this guide.
Earlier editorial risk estimate
This historical rating has not been recalculated by this documentation review.