Docs Home → MongoDB Cluster-to-Cluster Sync
mongosync

On this page
Description
The mongosync
binary is the primary process used in
Cluster-to-Cluster Sync. mongosync
migrates data from one cluster to
another and can keep the clusters in continuous sync.
This document provides a complete overview of the mongosync
command
line options.
Note
Both the source cluster and destination cluster must use MongoDB 6.0 or later.
mongosync
supports replica sets and sharded clusters.Standalone MongoDB instances are not supported. Convert the standalone instance to a replica set before using Cluster-to-Cluster Sync.
Options
Global Options
--cluster0 <URI>
Sets the connection URI for the first cluster. The first cluster can serve as either the source or the destination in the sync process. Designate the source and destination clusters in the call to the
start
API endpoint.For more information on connecting
mongosync
, see Connections.To set the
--cluster0
option from a configuration file, see thecluster0
setting.
--cluster1 <URI>
Sets the connection URI for the first cluster. The first cluster can serve as either the source or the destination in the sync process. Designate the source and destination clusters in the call to the
start
API endpoint.For more information on connecting
mongosync
, see Connections.To set the
--cluster1
option from a configuration file, see thecluster1
setting.
--config <filename>
Sets the path to the configuration file.
For more information, see Cluster Independence.
--id <ID>
Sets an identifier for the
mongosync
instance.Use this option when running multiple instances of
mongosync
on a sharded cluster, to synchronize the shards individually.The identifier value for this option must correspond to the shard ID of the shard it syncs. To find the shard ID, use the
listShards
command.To set the
--id
option from a configuration file, see theid
setting.
--logPath <DIR>
Sets the path to the log directory. Cluster-to-Cluster Sync writes logs to files in this directory.
For more information, see Logging.
To set the
--logPath
option from a configuration file, see thelogPath
setting.
--port
Default:
27182
Sets the port used by the HTTP server for the Cluster-to-Cluster Sync HTTP API.
To set the
--port
option from a configuration file, see theport
setting.
--verbosity <level>
Default:
INFO
Sets the verbosity level to use in log messages. Cluster-to-Cluster Sync logs all messages at the specified level and any messages at lower levels.
The
--verbosity
option supports the following values:TRACE
DEBUG
INFO
WARN
ERROR
FATAL
PANIC
To set the
--verbosity
option from a configuration file, see theverbosity
setting.
Behavior
Commit
To stop syncing, use the commit command on the
destination cluster to convert indexes and finalize the changes. While
commit
is running:
Writes are blocked on the source cluster.
Writes are blocked on the destination cluster until
mongosync
begins index validation.
To monitor the commit
process, use the progress command:
The destination cluster is writable when
canWrite
is true.Index conversion is complete when
mongosync
enters theCOMMITTED
state.
Cluster Independence
mongosync
syncs collection data between a source cluster and
destination cluster. mongosync
does not synchronize users or roles. As a result, you can create
users with different access permissions on each cluster.
Configuration File
Options for mongosync
can be set in a YAML configuration file. Use
the --config
option. For example:
$ mongosync --config /etc/mongosync.conf
For information on available settings, see Configuration.
Consistency
mongosync
supports eventual consistency on the destination
cluster. Read Consistency is not guaranteed on the destination cluster,
the source and destination clusters may differ at a given point in
time. However, if new writes are halted on the source cluster, the
source and destination clusters will eventually hold the same data.
Individual writes may be reordered or combined as they are relayed from source to destination. For a given document, the total number of writes may differ between source and destination.
Transactions may appear non-atomically on the destination cluster. Retryable writes may not be retryable on the destination cluster.
Profiling
If profiling is enabled on a source database, MongoDB creates a special
collection named <db>.system.profile
. After synchronization is
complete, Cluster-to-Cluster Sync will not drop the
<db>.system.profile
collection from the destination even if the
source database is dropped at a later time. The <db>.system.profile
collection will not change the accuracy of user data on the
destination.
Sharded Clusters
Cluster-to-Cluster Sync supports replication between sharded clusters. Individual shards are replicated in parallel from the source cluster to the destination cluster, however a chunk migration or similar source update could move documents to a new source shard during replication.
Even if documents move between source shards during replication, Cluster-to-Cluster Sync maintains the eventual consistency guarantee on the destination cluster.
Views
If a database with views is dropped on the source, the destination may
show an empty system.views
collection in that database. The empty
system.views
collection will not change the accuracy of user
data on the destination.
Write Blocking
By default, write-blocking is not enabled during synchronization. When
write-blocking is enabled, mongosync
blocks writes:
On the destination cluster during replication
On the source cluster while committing
To enable write-blocking, use the start API
to set enableUserWriteBlocking
to true
.
Reverse synchronization requires
write-blocking. To enable reverse synchronization between the source
and destination clusters, use the start API
to initiate replication
with reversible
and enableUserWriteBlocking
set to true
.
The options must be set when replication begins, they cannot be updated
later.
To set enableUserWriteBlocking
, the mongosync
user must have a
role that includes the setUserWriteBlockMode
and
bypassWriteBlockingMode
ActionTypes.
Note
When using enableUserWriteBlocking
, writes are only blocked for users
that do not have the bypassWriteBlockingMode
ActionType. Users
who have this ActionType are able to perform writes.
Examples
Deploy a source and a destination cluster.
Initialize Cluster-to-Cluster Sync:
mongosync \ --cluster0 'mongodb://192.0.2.10:27017,192.0.2.11:27017,192.0.2.12:27017' \ --cluster1 'mongodb://192.0.2.20:27017,192.0.2.21:27017,192.0.2.22:27017' Use the appropriate connection strings for the
--cluster0
and--cluster1
options so that they can connect to your replica sets.To start the synchronization process, use an HTTP client such as cURL to send the
start
command tomongosync
:curl localhost:27182/api/v1/start -X POST \ --data '{ "source": "cluster0", "destination": "cluster1" }' Example Output:
{ "success": true }