Docs Menu

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:

  1. Define a source and a destination cluster.

  2. Define administrative users.

  3. Download and install mongosync.

  4. Connect the clusters.

Follow the instructions below to setup Cluster-to-Cluster Sync.

1

Define a source and a destination cluster

If you already have a MongoDB cluster, either self-managed or hosted in MongoDB 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.

Tip

See also:

For more information on MongoDB server version compatibility or cross-version migrations, see MongoDB Server Version Compatibility and Support.

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.

2

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:

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

3

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:

  1. Locate a host server for the mongosync executable that has network connectivity to your source and destination clusters.

  2. Go to the MongoDB Download Center.

  3. Download the mongosync package for your host system.

  4. Unpack the mongosync package. The mongosync executable is in the bin directory.

For operating system specific installation instructions, see Installation.

4

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 '{ }'

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

    To determine the correct the user permissions for your use case, see User Permissions.

  • 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 SyncInstallation →

On this page

Share Feedback