mongosync binaries are not supported or tested for use with non-genuine MongoDB deployments. While the tools may work on these deployments, compatibility is not guaranteed.The mongosync binary is the primary process used in Cluster-to-Cluster Sync. mongosync migrates data from a source cluster to a destination cluster.
mongosync replicates data and writes from one cluster to another until the sync is finalized. You can use this tool to perform one-time data migrations between MongoDB clusters with minimal downtime.
For more information about mongosync and destination cluster behavior during execution, see Mid-sync Considerations.
Important
Until you've called commit on mongosync and canWrite successfully returns true, the destination cluster cannot be used to accept application read or write traffic. Do not use mongosync for maintaining Disaster Recovery clusters.
mongosync keeps track of its current actions through states. mongosync enters different states depending on the requests it receives. The current mongosync state determines which API operations you can run.
Note
Most state transitions happen as the result of an API call. The exceptions are:
The transition from
COMMITTINGtoCOMMITTED. For more information, see Finalizing Sync.The transition from
REVERSINGtoRUNNING. For more information, see Reversing Sync.
To view the current state of mongosync, use the /progress endpoint.
The following diagram illustrates the relationship between mongosync states and API operations:
The Frequently Asked Questions (FAQ) page addresses questions users have asked about mongosync.
Details
Connect Source and Destination Clusters
You must create an initial connection to the source and destination clusters before mongosync can start to sync data. For more information, see Connecting mongosync.
When mongosync connects to the source and destination clusters, the synchronization process enters the IDLE state.
Start Sync
To start the synchronization process, call the start endpoint.
The start endpoint begins the RUNNING state, which is when mongosync syncs data from the source cluster to the destination cluster. If you make subsequent writes to the source cluster, mongosync applies the operations to the destination cluster.
For every source collection that syncs, mongosync creates a corresponding collection on the destination.
mongosync temporarily alters some of the replicated collection characteristics in the destination cluster. It changes these destination cluster characteristics back to the source cluster characteristics during the COMMIT state. For more information, see Collection Characteristic Changes.
The RUNNING state includes two phases:
Collection Copy
During the collection copy phase, mongosync executes the initial data transfer from the source cluster to the destination cluster. mongosync performs this data transfer by splitting the source collections into partitions and copying the partitions to their corresponding destination collections.
Change Event Application
The change event application (CEA) phase starts after the collection copy phase ends.
During the CEA phase, mongosync makes ongoing changes to the destination cluster as you write to the source cluster.
To make ongoing updates to the destination cluster, mongosync opens a change stream on the source cluster and applies the change events it receives to the destination cluster.
When the CEA phase begins, mongosync applies the change events that are received during the collection copy phase before processing the events that are received during the CEA phase.
Pause Sync
To pause the sync process and enter the PAUSED state, call the pause endpoint.
To resume a paused sync process and return mongosync to the RUNNING state, call the resume endpoint.
Finalize Sync
To finalize the sync between the source and destination clusters, call the commit endpoint.
Note
You must block writes to the source cluster before you begin the the commit process.
If you previously set enableUserWriteBlocking to "sourceAndDestination" when you used the start endpoint, mongosync automatically blocks writes on the source cluster when you use the commit endpoint.
If you did not set enableUserWriteBlocking to "sourceAndDestination", run setUserWriteBlockMode on the source cluster to block writes.
The commit endpoint starts the COMMITTING state, which is when mongosync stops migrating data between the source and destination clusters.
When the COMMITTING state begins, mongosync retrieves the commit timestamp, which is the time of the most recent operation on the source cluster.
If there are no errors, mongosync sends a success message and exits CEA by processing events up until the commit timestamp. mongosync also restores collection characteristics that mongosync temporarily alters during synchronization.
When the above process is completed, mongosync enters the COMMITTED state. The COMMITTED state indicates that the cutover process is finished.
Reverse Sync
To reverse the direction of a committed sync operation, call the reverse endpoint.
The reverse endpoint starts the REVERSING state. mongosync swaps the source and destination clusters and resumes applying change events.
If the reverse sync is successful, mongosync enters the RUNNING state. The synchronization continues in the reverse direction from the original sync job.
Learn More
To learn more about mongosync, see: