Docs Home → MongoDB Cluster-to-Cluster Sync

`mongosync`

On this page

Description

Options
Global Options
Behavior
Commit
Cluster Independence
Configuration File
Consistency
Profiling
Sharded Clusters
Views
Write Blocking
Examples

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 the cluster0 setting.

--cluster1 <URI>

For more information on connecting mongosync, see Connections.

To set the --cluster1 option from a configuration file, see the cluster1 setting.

--config <filename>

Sets the path to the configuration file.

For more information, see Cluster Independence.

--help, -h: Prints usage information to stdout.

--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 the id 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 the logPath 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 the port 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 the verbosity setting.

--version, -v: Prints mongosync version information to stdout.

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 the COMMITTED 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 to mongosync:
```
curl localhost:27182/api/v1/start -X POST \
      --data '{ "source": "cluster0", "destination": "cluster1" }'
```
Example Output:
```
{ "success": true }
```

← Reference Configuration →