Stay organized with collections
Save and categorize content based on your preferences.
Migrate to Firestore with MongoDB compatibility
This guide takes you through the step-by-step process of migrating your
MongoDB-compatible source database to a Firestore with MongoDB
compatibility database with minimal downtime.
About the migration process
The migration process has the following stages:
Preparation: You create resources required for the migration and set up
environment variables that will be used to run commands at later stages of
the migration process.
Import from the MongoDB-compatible source database: You use the
Datastream service to capture the contents of your
MongoDB-compatible source database and transfer them into a
Cloud Storage bucket.
Write data to Firestore with MongoDB compatibility
database: You use the Dataflow
service to transfer data from the Cloud Storage bucket into a
Firestore with MongoDB compatibility database.
This Dataflow pipeline will run concurrently with the
Datastream stream that is pulling data from the
MongoDB-compatible source database.
Migrate traffic to Firestore: At the appropriate point
in the procedure, you migrate your application read and write traffic to
the Firestore with MongoDB compatibility database and stop
the migration pipeline.
The following diagram summarizes the migration process:
Your MongoDB-compatible source database remains in a serving state while the data transfer
takes place:
The Datastream process captures both data at rest and
change events.
There will be a short period of partial unavailability when you have to shut
down write traffic to your source database. During this period, the
remainder of the change events is replicated to Firestore.
After the replication completes, the Firestore with MongoDB
compatibility database can become the new source of truth for your
application workload. All read and write traffic can be directed to the new
database.
Detailed migration steps
This section describes the migration in more detail.
The Datastream service creates a stream between a source and a
destination. In this case, the source is your current MongoDB-compatible
deployment, while the destination is Cloud Storage. This process has
the following steps:
Initiate a Dataflow pipeline to begin injecting the
captured data into your Firestore with MongoDB
compatibility database.
Monitor the stream
to identify important milestones in the migration process to determine
whether any errors were encountered during the data transfer.
When it's appropriate,
shut down write traffic
to the source database. After all data, including recent changes, was
replicated to the Firestore with MongoDB compatibility
database, redirect read traffic to the new destination.
Code examples in this guide are meant to be executed one after another. This
guide assumes that you configure your environment by setting up all environment
variables beforehand. Afterwards, you execute commands required for the
migration that use the already configured environment variables. We recommend
to use this approach. Because many commands use same environment variables, you
can reduce the chance of introducing errors between different stages of the
migration process.
As an alternative, you can replace the variables in command examples with the
same values that you set for corresponding environment variables.
If any of your data doesn't meet restrictions in the preceding categories:
We recommend to address these conditions in your dataset before starting the
migration process.
If you choose to proceed without changes, then documents that are affected by
the limitations will fail writing to Firestore and will be
sidelined.
You can decide on how these documents must be handled. If they are
converted to supported types, values, or sizes, they can be reprocessed.
Datastream has the following requirements:
The minimum major version of MongoDB supported by
Datastream is 4.0. For some minor versions, there are
minimum patch versions that are supported:
4.0.21
4.2.10
4.4.2
Your MongoDB cluster must support Change Streams. Your MongoDB deployment
must be configured as a
replica set or a
sharded cluster for Change
Streams to be enabled.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Migrate to Firestore with MongoDB compatibility\n===============================================\n\nThis guide takes you through the step-by-step process of migrating your\nMongoDB-compatible source database to a Firestore with MongoDB\ncompatibility database with minimal downtime.\n\nAbout the migration process\n---------------------------\n\nThe migration process has the following stages:\n\n1. **Preparation**: You create resources required for the migration and set up\n environment variables that will be used to run commands at later stages of\n the migration process.\n\n2. **Import from the MongoDB-compatible source database**: You use the\n Datastream service to capture the contents of your\n MongoDB-compatible source database and transfer them into a\n Cloud Storage bucket.\n\n3. **Write data to Firestore with MongoDB compatibility\n database**: You use the Dataflow\n service to transfer data from the Cloud Storage bucket into a\n Firestore with MongoDB compatibility database.\n\n This Dataflow pipeline will run concurrently with the\n Datastream stream that is pulling data from the\n MongoDB-compatible source database.\n4. **Migrate traffic to Firestore**: At the appropriate point\n in the procedure, you migrate your application read and write traffic to\n the Firestore with MongoDB compatibility database and stop\n the migration pipeline.\n\nThe following diagram summarizes the migration process:\n\nYour MongoDB-compatible source database remains in a serving state while the data transfer\ntakes place:\n\n- The Datastream process captures both data at rest and change events.\n- There will be a short period of partial unavailability when you have to shut\n down write traffic to your source database. During this period, the\n remainder of the change events is replicated to Firestore.\n\n- After the replication completes, the Firestore with MongoDB\n compatibility database can become the new source of truth for your\n application workload. All read and write traffic can be directed to the new\n database.\n\nDetailed migration steps\n------------------------\n\nThis section describes the migration in more detail.\n\nThe Datastream service creates a stream between a source and a\ndestination. In this case, the source is your current MongoDB-compatible\ndeployment, while the destination is Cloud Storage. This process has\nthe following steps:\n\n1. [Create a source Datastream connection profile](/firestore/mongodb-compatibility/docs/migrate-create-connection-profiles)\n for your Mongo source. Specific instructions depend on the type and the way\n your MongoDB-compatible source is deployed.\n\n2. [Create a Cloud Storage bucket](/firestore/mongodb-compatibility/docs/migrate-configure-resources#create-bucket)\n that will receive the data and the change events from your\n MongoDB-compatible source database.\n\n3. [Create a destination Datastream connection profile](/firestore/mongodb-compatibility/docs/migrate-create-connection-profiles#connection-profile-storage)\n that uses this Cloud Storage bucket.\n\n4. [Create and actuate a Datastream stream](/firestore/mongodb-compatibility/docs/migrate-import-from-source)\n that connects the source connection profile to the destination connection\n profile.\n\n5. [Initiate a Dataflow pipeline](/firestore/mongodb-compatibility/docs/migrate-write-to-destination) to begin injecting the\n captured data into your Firestore with MongoDB\n compatibility database.\n\n6. [Monitor the stream](/firestore/mongodb-compatibility/docs/migrate-traffic#migration-completion-milestones)\n to identify important milestones in the migration process to determine\n whether any errors were encountered during the data transfer.\n\n7. When it's appropriate,\n [shut down write traffic](/firestore/mongodb-compatibility/docs/migrate-traffic#shut-down-write-traffic)\n to the source database. After all data, including recent changes, was\n replicated to the Firestore with MongoDB compatibility\n database, redirect read traffic to the new destination.\n\n8. [Enable write traffic](/firestore/mongodb-compatibility/docs/migrate-traffic#migrate-write-traffic)\n to your Firestore with MongoDB compatibility database.\n\nAbout code examples\n-------------------\n\nCode examples in this guide are meant to be executed one after another. This\nguide assumes that you configure your environment by setting up all environment\nvariables beforehand. Afterwards, you execute commands required for the\nmigration that use the already configured environment variables. We recommend\nto use this approach. Because many commands use same environment variables, you\ncan reduce the chance of introducing errors between different stages of the\nmigration process.\n\nAs an alternative, you can replace the variables in command examples with the\nsame values that you set for corresponding environment variables.\n\nLimitations\n-----------\n\nFirestore with MongoDB compatibility has the following limitations:\n\n- Firestore doesn't support the following BSON types:\n\n - Undefined\n - DBPointer\n - JavaScript\n - Symbol\n- Firestore has the following restrictions on the `_id` field:\n\n - ObjectIDs, Longs, and Strings in the document `_id` field are supported.\n - 0L as `_id` is not supported.\n- Firestore has a 4MB document size limit.\n\nIf any of your data contains the listed conditions:\n\n- We recommend to address these conditions in your dataset before starting the\n migration process.\n\n- If you choose to proceed without changes, then documents that are affected by\n the limitations will fail writing to Firestore and will be\n sidelined.\n You can decide on how these documents must be handled. If they are\n converted to supported types, values, or sizes, they can be reprocessed.\n\nDatastream has the following requirements:\n\n- The minimum major version of MongoDB supported by\n Datastream is 4.0. For some minor versions, there are\n minimum patch versions that are supported:\n\n - 4.0.21\n - 4.2.10\n - 4.4.2\n- Your MongoDB cluster must support Change Streams. Your MongoDB deployment\n must be configured as a\n [replica set](https://www.mongodb.com/docs/manual/replication/) or a\n [sharded cluster](https://www.mongodb.com/docs/manual/sharding/) for Change\n Streams to be enabled.\n\nWhat's next\n-----------\n\nProceed to\n[Configure resources for migration](/firestore/mongodb-compatibility/docs/migrate-configure-resources)."]]
