About mongosync
On this page
The mongosync binary is the primary process used in
Cluster-to-Cluster Sync. mongosync migrates data from a source cluster to a
destination cluster and keeps the clusters in continuous sync until you
finalize the sync.
You can use mongosync to create
dedicated analytics, development, or testing clusters that mirror your
production environment.
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:
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 continuously
updates the destination cluster when you make changes to the source cluster.
To make continuous 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 true 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 true, run
setUserWriteBlockMode on the source cluster to
block writes.
The commit endpoint starts the COMMITTING
state, which is when mongosync stops continuous sync 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: