Connect Two Atlas Clusters

This version of the documentation is archived and no longer maintained. View the current documentation for up-to-date guidance on mongosync usage and instructions on how to upgrade your version of mongosync.

The mongosync utility creates a connection between MongoDB clusters. mongosync can connect to any of the following clusters:

self-managed clusters
MongoDB Atlas hosted clusters
a self-managed cluster and an Atlas hosted cluster

This page provides instructions to connect Atlas clusters using MongoDB Cluster-to-Cluster Sync. For additional details on connecting to an Atlas cluster, see Connect to a Database Deployment

Considerations

Both the source and destination Atlas clusters must use MongoDB 6.0 or later.
mongosync supports replica sets and sharded clusters.
mongosync doesn't support Atlas shared clusters or serverless instances. You can use mongosync only with M10 or higher Atlas clusters.

Connection Strings

mongosync uses a MongoDB URI connection string to connect Atlas clusters:

The SRV connection scheme has the form:
```
mongodb+srv://[username:password]@[clusterName].[host].mongodb.net/
```
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]@[clusterName].[host].mongodb.net/
```

mongosync requires the primary read preference to connect to the source and destination clusters. For more information, see Read Preference Options.

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.

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 Atlas permissions are:

Sync Type	Required Source Permissions	Required Destination Permissions
Default	atlasAdmin	atlasAdmin `bypassWriteBlockingMode`
Write-blocking or reversing	atlasAdmin `bypassWriteBlockingMode`	atlasAdmin `bypassWriteBlockingMode`

For details on Atlas roles, see: Built-In Roles and Privileges.

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.

Limitations

Before you attempt to run mongosync with an M10+ Atlas cluster, disable the Require Indexes for All Queries option.

Example

Gather Connection Information

The generic connection string format is:

mongodb://<user>:<password>@<clusterName>.<hostname>.mongodb.net/

You can get the connection string for the Atlas clusters from the Atlas UI. To learn more, see Connect to a Database Deployment.

The connection strings you gathered for cluster0 and cluster1 should resemble the following:

cluster0:
mongodb+srv://clusterAdmin:superSecret@cluster1Name.abc123.mongodb.net
cluster1:
mongodb+srv://clusterAdmin:superSecret@cluster2Name.abc123.mongodb.net

There is an database administrative user clusterAdmin with the password superSecret in the project that contains the clusters.

Connect the Source and Destination Clusters with `mongosync`

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+srv://clusterAdmin:superSecret@cluster1Name.abc123.mongodb.net" \
      --cluster1 "mongodb+srv://clusterAdmin:superSecret@cluster2Name.abc123.mongodb.net"

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+srv://clusterAdmin:superSecret@cluster1Name.abc123.mongodb.net/admin?tls=true" \
   --cluster1 "mongodb+srv://clusterAdmin:superSecret@cluster2Name.abc123.mongodb.net/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@cluster1Name.abc123.mongodb.net/" \
   --cluster1 "mongodb+srv://clusterAdmin:superSecret@cluster2Name.abc123.mongodb.net/"

For more details about mongodb+srv connection strings, see SRV Connection Format.

Back

Connect

Self-Managed Clusters