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.
mongosync
does not support Atlas shared clusters or serverless instances.For a full list of limitations, see Cluster-to-Cluster Sync Limitations.
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 second cluster. The second 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.
--disableTelemetry
New in version 1.4.0.
Disables the collection of telemetry data for
mongosync
.By default,
mongosync
collects anonymous, aggregated usage data to improve MongoDB products. When you runmongosync
you can disable collection of this telemetry data.To set the
--disableTelemetry
option from a configuration file, see thedisableTelemetry
setting.For more information, see User Data Collection.
--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.
--loadLevel <level>
Type: integer
Default:
3
Sets the cluster workload level for syncing data between the source and destination clusters:
4
, the highest setting, maximizes cluster workload and syncs data the fastest.1
, the lowest setting, minimizes cluster workload and syncs data the slowest.
To set the
--loadLevel
option from a configuration file, see theloadLevel
setting.Warning
Setting
loadLevel
higher than the default of3
may negatively impact the destination cluster performance.
--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:
DEBUG
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
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
mongosync
does not enable write-blocking by default. If you enable
write-blocking, mongosync
blocks writes:
On the destination cluster during sync.
On the source cluster while
commit
is running.
To enable write-blocking, use the start API
to set enableUserWriteBlocking
to true
. You cannot enable
write-blocking after the sync starts.
You must enable write-blocking when you start mongosync
if you want
to use reverse synchronization later.
User Permissions
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.
Permissible Writes
To see what state mongosync
is in, call the /progress API endpoint. The /progress
output includes a
boolean value, canWrite
.
When
canWrite
istrue
, it is safe to write to the destination cluster.When
canWrite
isfalse
, do not write to the destination cluster.
You can safely write to the source cluster while mongosync
is
syncing. Do not write to the destination cluster unless canWrite
is
true
.
Commit
To stop syncing, use the commit command on the
destination cluster to convert indexes and finalize the changes. By default,
commit
operations have no effect on writes unless you enable
write-blocking. If you enable write blocking:
commit
blocks writes on the source cluster.commit
blocks writes on the destination cluster untilmongosync
begins index validation.
The commit
operation should take less than a few minutes. 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.
Read and Write Concern
By default, mongosync
sets the read concern level to
"majority"
for reads on the source cluster. For writes on
the destination cluster, mongosync
sets the write concern level to
"majority"
with j: true.
For more information on read and write concern configuration and behavior, see Read Concern and Write Concern.
Capped Collections
Starting in 1.3.0, Cluster-to-Cluster Sync supports capped collections with some limitations.
The minimum server version is 6.0.
convertToCapped
is not supported. If you runconvertToCapped
,mongosync
exits with an error.cloneCollectionAsCapped
is not supported.
Capped collections on the source cluster work normally during sync.
Capped collections on the destination cluster have temporary changes during sync:
There is no maximum number of documents.
The maximum collection size is 1PB.
mongosync
restores the original values for maximum number of
documents and maximum document size during commit.
System Collections
Cluster-to-Cluster Sync does not replicate system collections to the destination cluster.
If you issue a dropDatabase
command on the source cluster,
this change is not directly applied on the destination cluster. Instead,
Cluster-to-Cluster Sync drops user collections and views in the database
on the destination cluster, but it does not drop system collections
on that database.
For example, on the destination cluster:
The drop operation does not affect a user-created
system.js
collection.If you enable profiling, the
system.profile
collection remains.If you create views on the source cluster and then drop the database, replicating the drop removes the views, but leaves an empty
system.views
collection.
In these cases, the replication of dropDatabase
removes all user-created
collections from the database, but leaves its system collections on the
destination cluster.
Resilience
mongosync
is resilient and able to handle non-fatal errors. Logs
that contain the word "error" or "failure" do not indicate that
mongosync
is failing or corrupting data. For example, if a network
error occurs, the mongosync
log may contain the word "error' but
mongosync
is still able to complete the sync. In the case that a
sync does not complete, mongosync
writes a fatal log entry.
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 }