Docs Menu

Docs HomeMongoDB Cluster-to-Cluster Sync

Connect a Self-Managed Cluster to Atlas

On this page

  • Connection Strings
  • Authentication
  • Roles
  • Behavior
  • Example

The mongosync utility creates a connection between MongoDB clusters. mongosync can make a connection between:

  • self-managed clusters,

  • 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

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.

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.

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
  • readAnyDatabase

  • backup

  • clusterMonitor

default
destination cluster
  • readWriteAnyDatabase

  • restore

  • clusterMonitor

  • clusterManager

write-blocking or reversing
source cluster
  • readWriteAnyDatabase

  • backup

  • restore

  • clusterMonitor

  • clusterManager

write-blocking or reversing
destination cluster
  • readWriteAnyDatabase

  • backup

  • restore

  • clusterMonitor

  • clusterManager

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
  • atlasAdmin

  • backup

default
destination cluster
  • atlasAdmin

write-blocking or reversing
source cluster
  • atlasAdmin

  • backup

  • bypassWriteBlockMode privilege

write-blocking or reversing
destination cluster
  • atlasAdmin

  • backup

  • bypassWriteBlockMode privilege

For details on Atlas roles, see: Atlas User Roles.

To update Atlas user permissions, see: Manage Access to a Project.

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.

When mongosync connects, it is in the IDLE state. You must issue the start command to begin syncing.

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.

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.

←  Connect Two Self-Managed ClustersUse mongosync on Sharded Clusters →
Share Feedback