Docs Home → MongoDB Cluster-to-Cluster Sync
Quickstart
On this page
Overview
MongoDB Cluster-to-Cluster Sync connects MongoDB clusters and provides a way
to synchronize data between them. The tool that makes the connection is
mongosync
. This page provides a short introduction to help
you get started with Cluster-to-Cluster Sync. For more details, please see
the rest of the Cluster-to-Cluster Sync documentation.
Setup
Cluster-to-Cluster Sync syncs data between two clusters. To run
mongosync
, you will need to:
Define a source and a destination cluster.
Define administrative users.
Download and install
mongosync
.Connect the clusters.
Follow the instructions below to setup Cluster-to-Cluster Sync.
Define a source and a destination cluster
If you already have a MongoDB cluster, either self-managed or hosted in MongoDB Atlas, use that cluster as the source cluster. If you don't have a cluster to work with, you will need to create one.
This Quickstart works when the destination cluster and the source
cluster are both replica sets. To sync from a replica set to a
sharded cluster, or between sharded clusters, see:
Use mongosync
on Sharded Clusters.
Tip
See also:
For more information on MongoDB server version compatibility or cross-version migrations, see MongoDB Server Version Compatibility and Support.
The number of nodes in the destination replica set does not have to equal the number of nodes in the source replica set.
If your clusters are self-managed, they must be MongoDB Enterprise clusters. Cluster-to-Cluster Sync is only supported on MongoDB Community Edition in a limited number of cases. For more information on using Cluster-to-Cluster Sync with MongoDB Community Edition, contact a MongoDB sales representative.
Creating a cluster is beyond the scope of this guide. If you need help, refer to the documentation to create an Atlas cluster or to create a self-managed cluster.
Define administrative users
If either cluster is hosted in Atlas, or if either of them requires authentication, you must create a database user that has permissions in both clusters.
Source Cluster Authentication Requirements
The source user must have the following roles:
readAnyDatabase
roleclusterMonitor
rolebackup
role
In addition, the source user must be able to:
Run the
getParameter
command
If the source cluster is hosted in Atlas, the user must have the Atlas admin role. The user must also be able to read the change stream for the cluster.
Destination Cluster Authentication Requirements
If the destination cluster is hosted in Atlas, the user must have the Atlas admin role.
Cluster Authentication Notes
To add an Atlas user, see: Configure Database Users.
To add a user to a self-managed cluster, see: Create a User.
To verify user permissions, run
db.getUser()
.
Download and install mongosync

mongosync
is the tool that connects the source and
destination clusters. You can host mongosync
on its own
hardware, mongosync
does not have to run on the hardware that
hosts your MongodDB clusters.
To install mongosync
:
Locate a host server for the
mongosync
executable that has network connectivity to your source and destination clusters.Go to the MongoDB Download Center.
Download the
mongosync
package for your host system.Unpack the
mongosync
package. Themongosync
executable is in thebin
directory.
For operating system specific installation instructions, see Installation.
Connect the Clusters
A connection string contains the network and authentication
details that mongosync
needs to connect to the source and
destination clusters.
Determine the hostname or IP address and port for your source and destination clusters. You will use this information and the user authentication details to construct the connection strings.
The standard URI connection scheme has the form:
mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]
Your connections strings will resemble:
cluster0: mongodb://clusterAdmin:superSecret@clusterOne01.fancyCorp.com:20020,clusterOne02.fancyCorp.com:20020,clusterOne03.fancyCorp.com:20020 cluster1: mongodb://clusterAdmin:superSecret@clusterTwo01.fancyCorp.com:20020,clusterTwo02.fancyCorp.com:20020,clusterTwo03.fancyCorp.com:20020
For more details, see Connecting mongosync
.
Initialize mongosync

mongosync
must create an initial connection to the source and
destination clusters before it can start to sync data. To create the
initial connection, issue the following command on a single line (the
command is reformated here for clarity):
./bin/mongosync \ --cluster0 "mongodb://clusterAdmin:superSecret@clusterOne01.fancyCorp.com:20020,clusterOne02.fancyCorp.com:20020,clusterOne03.fancyCorp.com:20020" \ --cluster1 "mongodb://clusterAdmin:superSecret@clusterTwo01.fancyCorp.com:20020,clusterTwo02.fancyCorp.com:20020,clusterTwo03.fancyCorp.com:20020"
Initialization Notes
When
mongosync
first connects to the source and destination clusters it is in the IDLE state.mongosync
does not synchronize data until it receives the start command.Designate the source and destination clusters with the start command. "cluster0" and "cluster1" are just labels, either cluster can be
cluster0
orcluster1
.
Synchronize Data Between Clusters
The command interface for mongosync
is an HTTP server that
publishes an HTTP API. To control mongosync
, use the API endpoints.
The start command initiates data synchronization.
To start syncing, use curl
or a similar program to issue the
start command:
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1" } '
Once started, mongosync
will synchronize existing data on the
source cluster with the destination cluster. After the initial sync has
completed, new writes to the source cluster will be synced with the
destination cluster.
The API documentation provides details on using the following endpoints:
Endpoint | Description |
---|---|
Starts the synchronization between a source and destination
cluster. | |
Returns the status of the synchronization process. | |
Pauses the current synchronization operation. | |
Resumes a paused synchronization session based on data stored on
the destination cluster. | |
Commits the synchronization operation to the destination
cluster. | |
Reverses the direction of a committed sync operation. |
Synchronization Notes
The default port for the HTTP API is
27182
. Use the--port
option withmongosync
to configure another portmongosync
can swap the source and destination clusters to enable reverse synchronization. To usereverse synchronization
, you must pass these additional fields when you startmongosync
:reverse
enableUserWriteBlocking
curl localhost:27182/api/v1/reverse -XPOST --data '{ }' The user specified in the
mongosync
connection string must have the required permissions on the source and destination clusters. The permissions vary depending on your environment and if you want to run a write-blocking or reverse sync.To determine the correct the user permissions for your use case, see User Permissions.
You may need to increase the file descriptor
ulimits
on the host that is runningmongosync
. This applies to any UNIX-like system, but macOS in particular has low defaults. See UNIX ulimit settings.To estimate the size of
oplog
needed for initial synchronization, see oplog Sizing.