Docs Home → MongoDB Cluster-to-Cluster Sync

Quickstart

On this page

Overview

Setup
Define a source and a destination cluster
Define administrative users
Download and install mongosync
Connect the Clusters
Initialize mongosync
Initialization Notes
Synchronize Data Between Clusters
Synchronization Notes

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 MongodDB 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.

The source and destination clusters must be:

at least MongoDB 6.0.
the same server version
at least Feature Compatibility Version 6.0
the same Feature Compatibility Version

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:

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. The mongosync executable is in the bin 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 or cluster1.

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
`start`	Starts the synchronization between a source and destination cluster.
`progress`	Returns the status of the synchronization process.
`pause`	Pauses the current synchronization operation.
`resume`	Resumes a paused synchronization session based on data stored on the destination cluster.
`commit`	Commits the synchronization operation to the destination cluster.
`reverse`	Reverses the direction of a committed sync operation.

Synchronization Notes

The default port for the HTTP API is 27182. Use the --port option with mongosync to configure another port
mongosync can swap the source and destination clusters to enable reverse synchronization. To use reverse synchronization, you must pass these additional fields when you start mongosync:
- reverse
- enableUserWriteBlocking
```
curl localhost:27182/api/v1/reverse -XPOST --data '{ }'
```

Note

To use mongosync in the reverse direction, you must create a custom role that grants the following ActionTypes:

The setUserWriteBlockMode and bypassWriteBlockingMode ActionTypes are available starting in MongoDB 6.0. To create the custom roles, all clusters in a project must be on MongoDB 6.0 or higher.

You may need to increase the file descriptor ulimits on the host that is running mongosync. 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.

← Cluster-to-Cluster Sync Installation →

Quickstart.css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}