> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Mongosync Quickstart

## Overview

Mongosync replicates data and writes from one cluster to another until the sync is [finalized](https://www.mongodb.com/docs/mongosync/current/about-mongosync.md#std-label-c2c-about-finalizing). You can use this tool to perform one-time data migrations between MongoDB clusters with minimal downtime.

For more information about `mongosync` and destination cluster behavior during execution, see [Mid-sync Considerations.](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-mongosync-considerations)

The [mongosync](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-label-c2c-mongosync) binary is the primary process used in Mongosync.

- Each cluster can be a replica set or a sharded cluster.  If either is a sharded cluster, consult the [sharded cluster limitations](https://www.mongodb.com/docs/mongosync/current/reference/limitations.md#std-label-c2c-sharded-limitations) for `mongosync`.

- Sharded clusters are not required to have the same number of shards.

- The destination cluster must be the same version or up to two versions ahead of the source cluster. The patch version is not important, so long as they meet the minimum patch [version requirements.](https://www.mongodb.com/docs/mongosync/current/reference/supported-server-version.md#std-label-c2c-server-version-compatibility)

- The source cluster can remain active until commit because `mongosync` syncs writes on the source cluster for the duration of the migration until commit is called.

**Important:**

Until you've called [`commit`](https://www.mongodb.com/docs/mongosync/current/reference/api/commit.md#std-label-c2c-api-commit) on `mongosync` and `canWrite` successfully returns `true`, the migrated collections on the destination cluster cannot be used to accept application read or write traffic. Do not use `mongosync` to maintain secondary clusters for Disaster Recovery, Analytics, or other similar use cases.

Follow the instructions below to set up Mongosync, connect your clusters, and synchronize your data.

## Setup

1. Define a source and a destination cluster

   If you already have a MongoDB cluster, either self-managed or hosted in [MongoDB Atlas](https://www.mongodb.com/docs/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, see [Sync a Replica Set to a Sharded Cluster](https://www.mongodb.com/docs/mongosync/current/topologies/rs-to-sharded.md#std-label-c2c-rs-to-sharded). To sync between sharded clusters, see [Sync Sharded Clusters.](https://www.mongodb.com/docs/mongosync/current/topologies/multiple-mongosyncs.md#std-label-c2c-sharded-clusters)

   You can migrate between clusters on the same or different MongoDB versions. For more information on MongoDB server version compatibility or cross-version migrations, see [MongoDB Server Version Compatibility.](https://www.mongodb.com/docs/mongosync/current/reference/supported-server-version.md#std-label-c2c-server-version-compatibility)

   The number of nodes in the destination replica set does not have to equal the number of nodes in the source replica set.

   IMPORTANT:

   The destination cluster must have enough disk storage to accommodate the logical data size being migrated and the destination oplog entries from the initial sync. For example, to migrate 10 GB of data, the destination cluster must have at least 10 GB available for the data and another 10 GB for the insert oplog entries from the initial sync.

   To use [embedded verification](https://www.mongodb.com/docs/mongosync/current/reference/verification/embedded.md#std-label-c2c-embedded-verifier), you must have a larger oplog on the destination. If you enable the embedded verifier and reduce the size of the destination oplog, the embedded verifier might not be able to keep up, causing `mongosync` to error.

   If you need to reduce the overhead of the destination oplog entries and the embedded verifier is disabled, you can:

   - Use the [`oplogSizeMB`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-replication.oplogSizeMB) setting to lower the destination cluster's oplog size.

   - Use to [`oplogMinRetentionHours`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-storage.oplogMinRetentionHours) setting to lower or remove the destination cluster's minimum oplog retention period.

   If your clusters are self-managed, they must be MongoDB Enterprise clusters. Mongosync is only supported on MongoDB Community Edition in a limited number of cases. For more information on using Mongosync 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](https://www.mongodb.com/docs/atlas/tutorial/create-new-cluster.md#std-label-create-new-cluster) or to create a [self-managed cluster.](https://www.mongodb.com/docs/manual/tutorial/deploy-replica-set.md#std-label-server-replica-set-deploy)

   **Important:**

   Do not choose Latest Version With Auto Upgrades. This option auto upgrades your cluster to the latest minor release. Some minor releases, such as MongoDB version 8.2, may not support Live Migration or Mongosync. When [upgrading](https://www.mongodb.com/docs/atlas/tutorial/major-version-change.md#std-label-upgrade-major-MongoDB-version), choose a major version to ensure compatibility with Live Migration and Mongosync.

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:

   - [`readAnyDatabase`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-readAnyDatabase) role

   - [`clusterMonitor`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-clusterMonitor) role

   - [`backup`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-backup) role

   In addition, the source user must be able to:

   - Run the [`getParameter`](https://www.mongodb.com/docs/manual/reference/command/getParameter.md#mongodb-dbcommand-dbcmd.getParameter) command

   If the source cluster is hosted in Atlas, the user must have the [Atlas admin](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#std-label-atlas-user-privileges) role. The user must also be able to read the [change stream](https://www.mongodb.com/docs/manual/changeStreams.md#std-label-changeStreams) for the cluster.

   ##### Destination Cluster Authentication Requirements

   If the destination cluster is hosted in Atlas, the user must have the [Atlas admin](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#std-label-atlas-user-privileges) role.

   ##### Cluster Authentication Notes

   - To add an Atlas user, see: [Configure Database Users.](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-mongodb-users)

   - To add a user to a self-managed cluster, see: [Create a User on Self-Managed Deployments.](https://www.mongodb.com/docs/manual/tutorial/create-users.md#std-label-create-users)

   - To verify user permissions, run [`db.getUser()`.](https://www.mongodb.com/docs/manual/reference/method/db.getUser.md#mongodb-method-db.getUser)

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.](https://www.mongodb.com/try/download/mongosync)

   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 [Install on Linux](https://www.mongodb.com/docs/mongosync/current/installation/install-on-linux.md#std-label-c2c-install-linux) or [Install on macOS.](https://www.mongodb.com/docs/mongosync/current/installation/install-on-macos.md#std-label-c2c-install-macos)

## Connect the Clusters

1. Format your connection strings

   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:

   ```shell
   mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]

   ```

   Your connections strings will resemble:

   ```shell
   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 the connection documentation for your cluster architecture: [Atlas to Atlas](https://www.mongodb.com/docs/mongosync/current/connecting/atlas-to-atlas.md#std-label-c2c-conn-atlas2atlas), [Self-Managed to Self-Managed](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-onprem.md#std-label-c2c-conn-oprem2onprem), or [Self-Managed to Atlas.](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-atlas.md#std-label-c2c-conn-onprem2atlas)

2. 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 with your connection strings on a single line (the command is reformatted here for clarity):

   ```shell
   ./bin/mongosync \
         --logPath /var/log/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](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-states.md#std-label-c2c-states-descriptions) state.

- `mongosync` does not synchronize data until it receives the [start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) command.

- Designate the source and destination clusters with the [start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) command. "cluster0" and "cluster1" are just labels, either cluster can be `cluster0` or `cluster1`.

## Migrate Data Between Clusters

The [start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) endpoint initiates data synchronization. To start syncing, use `curl` or a similar program to issue the [start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) request:

```shell
curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1"
   } '

```

If the [start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) request is successful, `mongosync` returns `{ "success": true }` and starts to synchronize existing data on the source cluster with the destination cluster. At this point, `mongosync` enters the `RUNNING` state and applies subsequent source cluster writes to the destination cluster.

To check the status of the sync, call the [progress](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) endpoint:

```shell
curl localhost:27182/api/v1/progress -XGET

```

If the `progress` response includes the field `canCommit: true`, you can call the `/commit` endpoint. See [Finalize Cutover Process.](https://www.mongodb.com/docs/mongosync/current/reference/cutover-process.md#std-label-c2c-cutover-process)

The command interface for `mongosync` is an HTTP server that publishes an HTTP API. To control `mongosync`, use the API endpoints. The API documentation provides details on using the following endpoints:

| Endpoint | Description |
| --- | --- |
| [`start`](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) | Starts the synchronization between a source and destination cluster. |
| [`progress`](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) | Returns the status of the synchronization process. |
| [`pause`](https://www.mongodb.com/docs/mongosync/current/reference/api/pause.md#std-label-c2c-api-pause) | Pauses the current synchronization operation. |
| [`resume`](https://www.mongodb.com/docs/mongosync/current/reference/api/resume.md#std-label-c2c-api-resume) | Resumes a paused synchronization session based on data stored on the destination cluster. |
| [`commit`](https://www.mongodb.com/docs/mongosync/current/reference/api/commit.md#std-label-c2c-api-commit) | Commits the synchronization operation to the destination cluster. |
| [`reverse`](https://www.mongodb.com/docs/mongosync/current/reference/api/reverse.md#std-label-c2c-api-reverse) | Reverses the direction of a committed sync operation. |

## Finalize Cutover Process

You can finalize a migration and transfer your application workload from the source to the destination cluster using the `mongosync` cutover process.

For more information, see [Finalize Cutover Process.](https://www.mongodb.com/docs/mongosync/current/reference/cutover-process.md#std-label-c2c-cutover-process)

`mongosync` stores its metadata in a database or multiple databases during migration. The metadata databases can be named any of the following:

- `__mdb_internal_mongosync`

- Anything beginning with `__mdb_internal_mongosync_verifier`

Drop any metadata databases after a successful migration.

**Warning:**

If you started the migration with `reversible` set to `true`, you cannot [reverse](https://www.mongodb.com/docs/mongosync/current/reverse-sync.md#std-label-c2c-reverse-process) the migration after you drop the metadata databases.

## Notes

- The default port for the HTTP API is `27182`.  Use the `--port` option with `mongosync` to [configure another port.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-config)

- `mongosync` can swap the source and destination clusters to enable [reverse synchronization.](https://www.mongodb.com/docs/mongosync/current/reference/api/reverse.md#std-label-c2c-api-reverse)

  For more information, see the [`reverse`](https://www.mongodb.com/docs/mongosync/current/reference/api/reverse.md#std-label-c2c-api-reverse) endpoint.

- 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 use reverse sync.

  To determine the correct the user permissions for your use case, see [User Permissions.](https://www.mongodb.com/docs/mongosync/current/reference/permissions.md#std-label-c2c-permissions-and-roles)

- 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.](https://www.mongodb.com/docs/manual/reference/ulimit.md#std-label-system-resource-utilization)

- To estimate the size of `oplog` needed for initial synchronization, see [oplog Sizing.](https://www.mongodb.com/docs/mongosync/current/reference/oplog-sizing.md#std-label-c2c-oplog-sizing)