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
COMMITTING
toCOMMITTED
. For more information, see Finalizing Sync.The transition from
REVERSING
toRUNNING
. 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.
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: