Coming from Firebase

Move a Firebase backend one part at a time

Firebase provides several independent backend products, including Cloud Firestore, Realtime Database, SQL Connect, Authentication, Cloud Storage, and Cloud Functions. Moving to Encore usually replaces direct client access with APIs defined using Encore's TypeScript or Go SDK, with authorization and data access handled in the backend. Those APIs and their infrastructure declarations form the application model Encore uses for local development and deployment.

There is no single Firebase project import. Firestore and Realtime Database use NoSQL data models, SQL Connect combines Cloud SQL for PostgreSQL with a managed GraphQL API, native SQL operations, and realtime query subscriptions, Firebase Authentication is an identity service, and Cloud Storage stores objects in Google Cloud Storage. Plan and validate each migration separately.

How the concepts map

FirebaseEncore
Cloud Firestore collections and documentsUsually a relational schema in an Encore SQL database; there is no direct document-database primitive
Realtime Database JSON treeAn application-specific SQL schema or an external database
Firebase SQL Connect schema, operations, and generated SDKsAn Encore SQL database and explicit API endpoints; the existing Cloud SQL instance can also remain external
Client SDK queries and Security RulesExplicit API endpoints, with authorization and validation in backend code
Firebase AuthenticationKeep Firebase Authentication as an external service, or use another identity provider with an Encore authentication handler
Cloud Storage for FirebaseAn Encore object storage bucket
Callable and HTTP Cloud FunctionsEncore API endpoints
Firestore, Auth, and Storage triggersPub/Sub subscribers or provider-specific integrations
Scheduled functionsCron jobs
Firestore and Realtime Database listenersNo direct equivalent; use streaming APIs and application-defined events, or retain Firebase
Cloud Functions secrets and other sensitive configurationEncore secrets, with values set per environment

These primitives are declared in application code using TypeScript or Go.

Firebase Hosting, App Hosting, Remote Config, Cloud Messaging, Analytics, Crashlytics, and App Check are separate products. They can remain in use where appropriate; Firebase Extensions is the exception, having been deprecated with a shutdown date of 31 March 2027, so plan its replacement alongside this migration. Declaring an Encore service does not migrate or replace any of them. If App Check protects a client operation you move, the client can send its App Check token to the new backend, where the endpoint verifies it with the Firebase Admin SDK.

Choose what to move

Inventory the Firebase SDK calls made by browser and mobile clients. Direct Firestore and Realtime Database access depends on Security Rules, local caching, and realtime listeners. Replacing those calls with Encore APIs changes both the trust boundary and, potentially, offline behavior.

For each Firebase product, choose whether to:

  • keep it and call it from Encore through the Firebase Admin SDK or its Google Cloud API
  • replace it with an Encore primitive or application service
  • move it to another provider and integrate that provider with Encore

The general PaaS migration guide covers Encore's deployment models and the migration sequence shared by hosted platforms.

Firestore

Firestore exports contain documents and collection structure; they are not Postgres dumps. Moving the data to an Encore SQL database requires a relational schema and a transformation step.

Plan the migration as follows:

  1. List the collections, subcollections, document references, indexes, and queries used by the application.
  2. Design SQL tables, keys, relationships, and indexes for those access patterns.
  3. Add database migrations and explicit Encore endpoints for the required operations.
  4. Export Firestore data to Cloud Storage using its managed export service, then write a repeatable transformation and load process for the new schema.
  5. Validate document counts as well as application-level relationships and aggregates.
  6. Account for writes that occur after the export before switching traffic.
  1. List the collections, subcollections, document references, indexes, and queries used by the application.
  2. Design SQL tables, keys, relationships, and indexes for those access patterns.
  3. Add database migrations and explicit Encore endpoints for the required operations.
  4. Export Firestore data to Cloud Storage using its managed export service, then write a repeatable transformation and load process for the new schema.
  5. Validate document counts as well as application-level relationships and aggregates.
  6. Account for writes that occur after the export before switching traffic.

A managed Firestore export is not an exact snapshot taken at the start of the operation and may include changes made while it runs. Use a maintenance window, a change-capture process, or another reconciliation strategy if the application must remain writable.

Firestore transactions, atomic field operations, server timestamps, geospatial conventions, and denormalized documents need explicit SQL equivalents. Test query semantics and contention behavior rather than translating documents mechanically.

SQL Connect

Firebase SQL Connect uses Cloud SQL for PostgreSQL together with a managed GraphQL API, native SQL operations, and generated client SDKs. It also offers realtime query subscriptions and client-side caching, which have no Encore equivalent and need replacing rather than porting. You can keep SQL Connect as an external dependency, or move its operations to Encore endpoints and manage the PostgreSQL schema through Encore migrations.

When deploying with Encore Cloud on GCP, a supported existing Cloud SQL instance can be connected through the Cloud SQL import workflow. Follow that guide's bootstrap-migration procedure for an existing schema, and choose one migration system to own future schema changes. If SQL Connect must continue managing the schema, leave the database external instead of applying Encore migrations to the same tables.

Realtime Database

Realtime Database stores data as a JSON tree. You can export a node and its children as JSON, then transform that JSON into the new database schema.

Review multi-location updates, generated keys, transactions, priorities, and denormalized paths before importing the data. A successful JSON load does not by itself preserve listener behavior or Security Rules.

If the application relies on offline persistence and automatic client synchronization from Firestore or Realtime Database, plan that feature separately. Encore endpoints and streaming APIs do not provide a drop-in offline database client.

Security Rules and API access

Firebase web and mobile SDKs can access Firestore, Realtime Database, and Cloud Storage directly, with Firebase Security Rules enforcing access. Server Firebase libraries instead use Google Cloud IAM or administrative credentials and can bypass those client rules.

With Encore, clients call API endpoints. The endpoint authenticates the caller, validates the request, performs authorization, and accesses the resource from backend code. Translate each relevant rule into tests and application checks before moving a client operation. Pay particular attention to ownership conditions, custom claims, field-level validation, query constraints, and rules that read other documents.

During coexistence, keep Security Rules for direct Firebase client traffic. Encore code using administrative credentials must enforce its own authorization; do not rely on the client rules to protect that path.

Authentication

Encore provides the authentication hook used by its API gateway, but it does not provide a hosted user directory or sign-in UI. You can keep Firebase Authentication by verifying Firebase ID tokens in an Encore authentication handler. Existing client sign-in flows can then continue while Encore protects its endpoints.

Encore provides the authentication hook used by its API gateway, but it does not provide a hosted user directory or sign-in UI. You can keep Firebase Authentication by verifying Firebase ID tokens in an Encore authentication handler. Existing client sign-in flows can then continue while Encore protects its endpoints.

If you move to another identity provider, Firebase CLI can export accounts as JSON or CSV. Password migration depends on whether the destination supports Firebase's password hash and parameters. Firebase exports only SCRYPT-backed password hashes; records originally imported with another algorithm can have empty hash fields until the user signs in and Firebase rehashes the password. Social-provider links, phone users, MFA enrollment, custom claims, email verification, and active sessions also require a provider-specific migration plan.

Keep Firebase UIDs as the destination subject identifier where possible. If identifiers change, update every Firestore document, Realtime Database path, SQL row, Storage rule, and application record that refers to the UID. Some migrations require users to sign in again or reset their passwords.

Cloud Storage

Cloud Storage for Firebase stores objects in Google Cloud Storage. You can keep the bucket as an external dependency, copy its objects to a new bucket declared with Encore, or connect a declared bucket to the existing GCS bucket through Encore Cloud's GCS import workflow.

Access through Google Cloud APIs or Encore uses Google Cloud IAM rather than Firebase Authentication and Storage Rules. Recreate the required authorization in your Encore APIs even when the objects remain in the same bucket.

When moving objects:

  1. Declare the target object storage bucket.
  2. Copy objects with Google Cloud Storage tools or a managed transfer service, preserving paths and required metadata.
  3. Replace Firebase Storage SDK calls and download URLs in clients.
  4. Implement the former Storage Rules as authorization checks in the Encore APIs that read, write, or issue signed URLs.
  5. Verify CORS, cache metadata, content types, object generations, and upload limits.
  1. Declare the target object storage bucket.
  2. Copy objects with Google Cloud Storage tools or a managed transfer service, preserving paths and required metadata.
  3. Replace Firebase Storage SDK calls and download URLs in clients.
  4. Implement the former Storage Rules as authorization checks in the Encore APIs that read, write, or issue signed URLs.
  5. Verify CORS, cache metadata, content types, object generations, and upload limits.

Firebase download tokens and URLs should not be expected to remain valid for copied objects. Keep the original bucket available until clients and stored URLs have been updated.

Cloud Functions

Map each function according to its trigger:

  • Move HTTP and callable functions to Encore API endpoints. Callable functions use a Firebase-specific request and response protocol, so update clients rather than exposing an Encore endpoint at the old URL without a compatibility layer.
  • Move scheduled functions to Encore cron jobs.
  • Move asynchronous application events to Pub/Sub topics and subscriptions.
  • Keep Firebase or Google Cloud event integrations for Firestore, Realtime Database, Authentication, and Storage events that remain outside Encore.

If Encore becomes the only writer for a workflow, it can publish an application event after a successful operation. If Firebase clients or other systems still write directly, publishing only from Encore would miss those changes.

Cloud Functions run in a Google-managed functions environment. Review runtime versions, request formats, environment configuration, concurrency, timeouts, retries, IAM, regional placement, and temporary filesystem assumptions when moving the code. Make event handlers idempotent before enabling retries in the replacement workflow.

Realtime clients

Encore streaming APIs (TypeScript) provide WebSocket streams between a client and an API handler. Pub/Sub distributes events between backend services. Together they can support application-defined updates, but they do not reproduce Firestore queries, local caches, Security Rules, or Realtime Database synchronization.

Define the client protocol explicitly: the initial data load, which changes produce events, authorization per connection, ordering, reconnect behavior, and recovery from missed messages. Retaining Firebase listeners while other parts move to Encore is often the smaller first step.

Run Firebase and Encore together

Store Firebase service-account credentials or other sensitive configuration in Encore secrets, and use the Firebase Admin SDK only from backend code. Grant the service account only the permissions the service requires.

Store Firebase service-account credentials or other sensitive configuration in Encore secrets, and use the Firebase Admin SDK only from backend code. Grant the service account only the permissions the service requires.

An incremental migration can follow this order:

  1. Deploy an Encore service and keep existing Firebase clients unchanged.
  2. Verify Firebase ID tokens in Encore and move selected operations behind Encore APIs.
  3. Move HTTP functions and backend-only workflows.
  4. Move client data access one query or workflow at a time, translating its Security Rules into backend authorization.
  5. Migrate Storage, Authentication, and realtime behavior independently if they need to move.
  6. Perform the final data transfer or reconciliation, switch traffic, and monitor both systems.

Avoid writing independently to Firebase and the replacement database unless you have designed conflict handling and reconciliation. Keep the old system available until the new data, authorization, and client behavior have been verified.

Firebase products retained during the migration remain in the Firebase and Google Cloud provisioning and billing lifecycle. Encore secrets and application code provide the integration; they do not transfer ownership of those resources to Encore.

Firebase Hosting can continue serving a frontend that calls an Encore API. Update its runtime configuration, rewrites, CORS policy, and custom-domain routing as required by the new API origin.

Before cutover

  • Compare document or node counts with the loaded rows and check application-level invariants.
  • Test sign-in, token refresh, authorization, account recovery, and any custom claims.
  • Verify Storage object counts, metadata, access checks, and persisted URLs.
  • Exercise listener reconnects, missed-event recovery, and offline behavior.
  • Check function retries, schedules, webhooks, and idempotency.
  • Update client configuration, CORS, callback URLs, Security Rules, and service-account permissions.
  • Keep a rollback path until the new deployment has handled production traffic successfully.

Next steps