Connect a Self-Managed Cluster to Atlas
The mongosync utility creates a connection
between MongoDB clusters. mongosync can connect to
any of the following clusters:
MongoDB Atlas hosted clusters
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
Note
For best performance, upgrade your on self-managed cluster to the most recent MongoDB Server patch release prior to migration. For more information, see Upgrade to the Latest Self-Managed Patch Release of MongoDB.
Connection Strings
mongosync uses a MongoDB URI
connection string to connect self-managed clusters:
The SRV connection scheme has the form:
mongodb+srv://[username:password@][host.domain.TLD][/defaultauthdb][?options] 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.
mongosync requires the primary read preference to
connect to the source and destination clusters. For more information,
see Read Preference Options.
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.
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
modify write-blocking settings or use reverse sync.
The self-managed permissions for the source cluster are:
Sync Type | Required Source Permissions |
|---|---|
Default | |
Dual Write-Blocking | |
Reversing | |
Multiple Reversals |
For details on server roles, see: Role-Based Access Control in Self-Managed Deployments.
To update user permissions, see: grantRolesToUser.
The Atlas permissions for the destination cluster are:
Sync Type | Required Destination Permissions |
|---|---|
Default |
|
Dual write-blocking, reversing, or multiple reversals |
|
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 source cluster, cluster0, is hosted on the following
servers and ports:
clusterOne01.fancyCorp.com:20020clusterOne02.fancyCorp.com:20020clusterOne03.fancyCorp.com:20020
The destination Atlas cluster, cluster1, is hosted on the
following servers and ports:
cluster2Name-01.abc123.com:27017cluster2Name-02.abc123.com:27017cluster2Name-03.abc123.com:27017
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 for the self-managed cluster is:
mongodb://<user>:<password>@<ip-address>:<port>,<ip-address>:<port>,<ip-address>:<port>
The generic connection string format for the Atlas cluster is:
mongodb://<user>:<password>@<clusterName>.<hostname>.mongodb.net/
Use the connection information you gathered for the self-managed cluster
to create the connection strings for cluster0:
cluster0: mongodb://clusterAdmin:superSecret@clusterOne01.fancyCorp.com:20020,clusterOne02.fancyCorp.com:20020,clusterOne03.fancyCorp.com:20020
You can get the connection string for the Atlas cluster from the Atlas UI. To learn more, see Connect to a Database Deployment.
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@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://clusterAdmin:superSecret@clusterOne01.fancyCorp.com:20020,clusterOne02.fancyCorp.com:20020,clusterOne03.fancyCorp.com:20020/admin?tls=true" \ --cluster1 "mongodb://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@clusterOne01.fancyCorp.com/" \ --cluster1 "mongodb+srv://clusterAdmin:superSecret@cluster2Name.abc123.mongodb.net/"
For more details about mongodb+srv connection strings, see
SRV Connection Format.