Docs Home → MongoDB Cluster-to-Cluster Sync
Connect a Self-Managed Cluster to Atlas
The mongosync utility creates a connection
between MongoDB clusters. mongosync
can make a connection between:
MongoDB Atlas hosted clusters, or
a self-managed cluster and an Atlas hosted cluster.
This page provides instructions to connect a self-managed cluster to an Atlas cluster using MongoDB Cluster-to-Cluster Sync.
For additional details on connecting to an Atlas cluster, see Connect to a Database Deployment
Connection Strings
mongosync uses a MongoDB URI connection string to connect clusters:
The SRV connection scheme has the form:
mongodb+srv://[username:password@][host.domain.TLD][:port][/defaultauthdb][?options] For information on how to find your SRV connection string in Atlas, see Connect to Your Cluster.
The standard URI connection scheme has the form:
mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]
Specify the hostnames of the mongod
instances the same way
that they are listed in your replica set configuration.
For sharded clusters, specify the
hostnames of the mongos
instances instead of the
mongod
instances.
Note
mongosync
does not require the replicaSet
option.
Authentication
Provide valid authentication to connect to a MongoDB Atlas cluster. If you do not already have an Atlas database user, you must create a user.
If either the source or destination cluster requires authentication,
you must give the correct credentials when calling mongosync
.
Roles
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.
The self-managed permissions are:
Sync Type | Target | Required Permissions |
---|---|---|
default | source cluster |
|
default | destination cluster |
|
write-blocking or reversing | source cluster |
|
write-blocking or reversing | destination cluster |
|
For details on server roles, see: Role-Based Access Control.
To update user permissions, see: grantRolesToUser
.
The Atlas permissions are:
Sync Type | Target | Required Permissions |
---|---|---|
default | source cluster |
|
default | destination cluster |
|
write-blocking or reversing | source cluster |
|
write-blocking or reversing | destination cluster |
|
For details on Atlas roles, see: Atlas User Roles.
To update Atlas user permissions, see: Manage Access to a Project.
Behavior
Hosting
The mongosync
utility can be hosted on its own hardware close to
either the source or destination cluster. It does not have to be hosted
on the same server as one of the mongod
or mongos
instances in the cluster. This flexibility allows you to push, or pull,
data to the destination cluster with minimal impact on the
mongod
or mongos
instances running there.
Initial State
When mongosync
connects, it is in the IDLE
state. You must
issue the start command to begin syncing.
Example
Gather Connection Information
The source cluster, cluster0
, is hosted on the following servers
and ports:
clusterOne01.fancyCorp.com:20020
clusterOne02.fancyCorp.com:20020
clusterOne03.fancyCorp.com:20020
The destination cluster, cluster1
, is hosted on the following
servers and ports:
clusterTwo01.fancyCorp.com:20020
clusterTwo02.fancyCorp.com:20020
clusterTwo03.fancyCorp.com:20020
There is an administrative user, clusterAdmin
configured on each
cluster with password, superSecret
.
Connect the Source and Destination Clusters with mongosync

The generic connection string format is:
mongodb://<user>:<password>@<ip-address>:<port>,<ip-address>:<port>,<ip-address>:<port>
Use the connection information you gathered to create the connection
strings for cluster0
and cluster1
:
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
The mongosync
command layout below is modified for display. To
connect cluster0
to cluster1
with mongosync
, enter the
following command on one line:
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"
Atlas clusters require TLS connections. To use mongosync
with Atlas
clusters, you add the tls=true
option. For example,
to connect to the admin
database on cluster0
and cluster1
:
mongosync \ --cluster0 "mongodb://clusterAdmin:superSecret@clusterOne01.fancyCorp.com:20020,clusterOne02.fancyCorp.com:20020,clusterOne03.fancyCorp.com:20020/admin?tls=true" \ --cluster1 "mongodb://clusterAdmin:superSecret@clusterTwo01.fancyCorp.com:20020,clusterTwo02.fancyCorp.com:20020,clusterTwo03.fancyCorp.com:20020/admin?tls=true"
You can also use mongodb+srv
connection strings with mongosync
.
You do not need to add the tls=true
option to a
mongodb+srv
connection string. For example:
mongosync \ --cluster0 "mongodb+srv://clusterAdmin:superSecret@clusterOne01.fancyCorp.com:20020/" \ --cluster1 "mongodb+srv://clusterAdmin:superSecret@clusterTwo01.fancyCorp.com:20020/"
For more details about mongodb+srv
connection strings, see
SRV Connection Format.