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

# `mongosync` Behavior

The `mongosync` binary is the primary process used in Mongosync. `mongosync` migrates data from one cluster to another.

For an overview of the `mongosync` process, see [About `mongosync`.](https://www.mongodb.com/docs/mongosync/current/about-mongosync.md#std-label-about-mongosync)

To get started with `mongosync`, refer to the [Quick Start Guide.](https://www.mongodb.com/docs/mongosync/current/quickstart.md#std-label-c2c-quickstart)

For more detailed information, see the installation or connection documentation that best fits your situation.

## Embedded Verifier Disclaimer

Starting in 1.9, `mongosync` includes an embedded verifier to perform a series of verification checks on all supported collections on the destination cluster to confirm that it was successful in transferring documents from the source cluster to the destination.

When you start the `mongosync` process, it provides the following disclaimer:

```text
Embedded verification is enabled by default. Verification checks for data 
consistency between the source and destination clusters. Verification will 
cause mongosync to fail if any inconsistencies are detected, but it does not 
check for all possible data inconsistencies. Please see the documentation at 
https://www.mongodb.com/docs/cluster-to-cluster-sync/current/reference/verification/embedded 
for more details. Verification requires approximately 0.5 GB of memory per 1 
million documents on the source cluster and will fail if insufficient memory 
is available. Accepting this disclaimer indicates that you understand the 
limitations and memory requirements for this tool. To skip this disclaimer 
prompt, use –-acceptDisclaimer.

To disable the embedded verifier, specify 'verification: false' when starting 
mongosync. Please see https://www.mongodb.com/docs/cluster-to-cluster-sync/current/reference/verification/ 
for alternative verification methods.

Do you want to continue? (y/n):

```

If you have already read and accepted the disclaimer, you can start `mongosync` with the [`--acceptDisclaimer`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--acceptDisclaimer) option to skip this notification.

## Settings

### Cluster Independence

`mongosync` syncs collection data between a source cluster and destination cluster. `mongosync` does not synchronize [users](https://www.mongodb.com/docs/manual/core/security-users.md#std-label-users) or [roles](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#std-label-built-in-roles). As a result, you can create users with different access permissions on each cluster.

### Configuration File

Options for `mongosync` can be set in a YAML configuration file. Use the [`--config`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--config) option. For example:

```shell
$ mongosync --config /etc/mongosync.conf

```

For information on available settings, see [Configuration.](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#std-label-c2c-config)

## Cluster and Collection Types

### Sharded Clusters

Mongosync supports replication between sharded clusters. A single mongosync deployment copies source data as partitions, regardless of which shard stores the data. In a multi-mongosync deployment, you run one `mongosync` instance for each source shard. The instances replicate their respective shards in parallel during the [change event application](https://www.mongodb.com/docs/mongosync/current/about-mongosync.md#std-label-c2c-cea) phase. However, `mongosync` does not preserve the source cluster's sharding configuration.

**Important:**

You must always disable the balancer on a sharded destination cluster by using [`balancerStop`](https://www.mongodb.com/docs/manual/reference/command/balancerStop.md#mongodb-dbcommand-dbcmd.balancerStop). After stopping the balancer, wait **fifteen minutes** before starting `mongosync`. This gives the cluster time to finish any in-progress chunk migrations.

If the source or destination cluster is a sharded cluster and you are not running `mongosync` with [namespace filtering](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-filtered-sync), you must disable the source cluster's balancer by running the [`balancerStop`](https://www.mongodb.com/docs/manual/reference/command/balancerStop.md#mongodb-dbcommand-dbcmd.balancerStop) command and waiting 15 minutes for the command to complete.

If the source or destination cluster is a sharded cluster and you are running `mongosync` with namespace filtering, you can globally enable the source cluster's balancer but you must disable it for all collections within the namespace filter. See [Disabling Balancer for Collections in Filtered Sync](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-disabling-balancer-filtered). You can also fully disable the source cluster's balancer.

During migration, do not run the [`moveChunk`](https://www.mongodb.com/docs/manual/reference/command/moveChunk.md#mongodb-dbcommand-dbcmd.moveChunk) or [`moveRange`](https://www.mongodb.com/docs/manual/reference/command/moveRange.md#mongodb-dbcommand-dbcmd.moveRange) commands. If you have enabled the source cluster's balancer, but disabled it for collections within the namespace filter, do not run [`shardCollection`](https://www.mongodb.com/docs/manual/reference/command/shardCollection.md#mongodb-dbcommand-dbcmd.shardCollection) on collections within the namespace filter. If you run [`shardCollection`](https://www.mongodb.com/docs/manual/reference/command/shardCollection.md#mongodb-dbcommand-dbcmd.shardCollection) on collections within the namespace filter during the migration, `mongosync` returns an error and stops, which requires you to start the migration from scratch.

**Note:**

`mongosync` does not support migrating into destination namespaces with pre-configured shard zone tags. Before starting a migration, remove all shard tag ranges, or zones, from any namespaces that `mongosync` will migrate into on the destination. You can re-add the desired zone ranges after the migration reaches the `COMMITTED` state.

#### Automatic Balancer Disabling

Starting in version 1.17, `mongosync` disables the balancer on source and destination clusters during initialization if it detects that the balancers are not disabled.

This only applies during initialization. If `mongosync` detects that either balancer is enabled after the migration begins, `mongosync` fails.

After disabling the balancer, `mongosync` waits for 15 minutes to ensure that in-progress chunk migrations complete before continuing with the migration.

If the migration is not reversible and `mongosync` disables the source or destination balancer during initialization, after a successful commit `mongosync` re-enables the balancer(s) it disabled. If the migration is reversible, `mongosync` does not re-enable any balancers to avoid making users wait 15 minutes.

IMPORTANT: If `mongosync` disables the balancer for either cluster and then fails before commit, you must re-enable the balancer(s) manually by using the [`balancerStart`](https://www.mongodb.com/docs/manual/reference/command/balancerStart.md#mongodb-dbcommand-dbcmd.balancerStart) database command if you do not plan to run `mongosync` again.

#### Disabling Balancer for Collections in Filtered Sync

If you are using a [namespace filter](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-filtered-sync) and want to enable your source cluster's balancer for collections outside the namespace filter, follow these instructions before you start `mongosync`.

1. Enable the balancer for the source cluster.

   Before starting `mongosync` with a [namespace filter](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-filtered-sync), enable the balancer for the source cluster by running the [`sh.startBalancer()`](https://www.mongodb.com/docs/manual/reference/method/sh.startBalancer.md#mongodb-method-sh.startBalancer) method in `mongosh`.

2. Disable the balancer for each collection.

   Disable the balancer for each collection within the namespace filter by running the [`setAllowMigrations`](https://www.mongodb.com/docs/manual/reference/command/setAllowMigrations.md#mongodb-dbcommand-dbcmd.setAllowMigrations) command:

   ```javascript
   db.adminCommand(
     { 
       setAllowMigrations: “<db>.<collection>”,
       allowMigrations: false
     }
   )

   ```

   Run the preceding command for every collection within the namespace filter.

**Important:**

If you enable the source cluster's balancer but do not use a namespace filter, or if you do not disable the balancer for all collections within the namespace filter, `mongosync` fails.

#### Pre-Split Chunks

When `mongosync` syncs to a sharded destination cluster, it pre-splits chunks for sharded collections on the destination cluster. For each sharded collection, `mongosync` attempts to create 90 chunks.

#### Chunk Distribution

**Important:**

Even if the source cluster is balanced, `mongosync` doesn't ensure balance of the destination cluster. Because `mongosync` doesn't support the execution of sharding operations during migration, you must wait until it is safe to accept writes to rebalance the destination cluster. See [Sharded Cluster Balancer](https://www.mongodb.com/docs/manual/core/sharding-balancer-administration.md#std-label-sharding-balancing) for guidance on how to rebalance the cluster and [sharded cluster limitations](https://www.mongodb.com/docs/mongosync/current/reference/limitations.md#std-label-c2c-sharded-limitations) for information on sharded cluster limitations in `mongosync`.

`mongosync` does not preserve chunk distribution from the source to the destination, even with multiple `mongosync` instances. It is not possible to reproduce a particular pre-split of chunks from a source cluster on the destination cluster.

The only sharding configuration that `mongosync` preserves from the source cluster to the destination cluster is the sharding key. Once the migration finishes, you can enable the destination cluster's balancer which distributes documents independently of the source cluster's distribution.

#### Primary Shards

When you sync to a sharded destination cluster, `mongosync` assigns a primary shard to each database by means of a round-robin.

**Warning:**

Running [`movePrimary`](https://www.mongodb.com/docs/manual/reference/command/movePrimary.md#mongodb-dbcommand-dbcmd.movePrimary) on the source or destination cluster during migration may result in a fatal error or require you to restart the migration from the start. For more information, see [Sharded Clusters.](https://www.mongodb.com/docs/mongosync/current/reference/limitations.md#std-label-c2c-sharded-limitations)

#### Config Shard Cluster

Starting in 8.0, MongoDB introduces support for config shard clusters, also known as embedded config server clusters.

`mongosync` supports sync from dedicated config server sharded clusters to embedded config server sharded clusters and vice versa. Additionally, `mongosync` supports sync from replica sets to config sharded clusters, but not vice versa.

To learn more about embedded config servers, see [Config Shard.](https://www.mongodb.com/docs/manual/core/config-shard.md#std-label-config-shard-concept)

### Multiple Clusters

To sync a source cluster to multiple destination clusters, use one `mongosync` instance for each destination cluster. For more information, see [Multiple Clusters Limitations.](https://www.mongodb.com/docs/mongosync/current/reference/limitations.md#std-label-multiple-clusters-limitations)

### Capped Collections

Starting in 1.3.0, Mongosync supports [capped collections](https://www.mongodb.com/docs/manual/core/capped-collections.md#std-label-manual-capped-collection) with some limitations.

Starting in 1.20.0, you must pass the [`--enableCappedCollectionHandling`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--enableCappedCollectionHandling) flag when starting `mongosync` to enable creating new capped collections during a migration.

- [`convertToCapped`](https://www.mongodb.com/docs/manual/reference/command/convertToCapped.md#mongodb-dbcommand-dbcmd.convertToCapped) is not supported. If you run `convertToCapped`, `mongosync` exits with an error.

- [`cloneCollectionAsCapped`](https://www.mongodb.com/docs/manual/reference/command/cloneCollectionAsCapped.md#mongodb-dbcommand-dbcmd.cloneCollectionAsCapped) is not supported.

Capped collections on the source cluster work normally during sync.

Capped collections on the destination cluster have temporary changes during sync:

- There is no maximum number of documents.

- The maximum collection size is 1PB.

`mongosync` restores the original values for maximum number of documents and maximum document size during commit.

## Reads and Writes

### Write Blocking

`mongosync` manages write blocking on the source and destination clusters internally based on your migration configuration:

| Configuration | Source writes blocked | Destination writes blocked |
| --- | --- | --- |
| Default | Yes | Yes |
| Source cluster runs MongoDB earlier than 6.0 | No | Yes |
| Namespace filtering enabled (`includeNamespaces` or `excludeNamespaces` specified in the `/start` request) | No | Yes |
| Pre-existing destination data enabled (`preExistingDestinationData` set to `true` in the `/start` request) | No | No |

`mongosync` blocks source writes after you call [/commit](https://www.mongodb.com/docs/mongosync/current/reference/api/commit.md#std-label-c2c-api-commit). Source writes remain blocked unless the migration fails with a managed error. If `mongosync` terminates unexpectedly during commit, you can unblock writes on the source cluster manually by running the following command:

```javascript
db.adminCommand(
   {
      setUserWriteBlockMode: 1,
      global: false
   }
)

```

For more information, see [`setUserWriteBlockMode`.](https://www.mongodb.com/docs/manual/reference/command/setUserWriteBlockMode.md#mongodb-dbcommand-dbcmd.setUserWriteBlockMode)

`mongosync` blocks destination writes after you call [/start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start). Destination writes remain blocked until `canWrite` is `true` in the [/progress](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) response.

#### User Permissions

The `mongosync` user must have a role that includes the [`setUserWriteBlockMode`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-setUserWriteBlockMode) and [`bypassWriteBlockingMode`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-bypassWriteBlockingMode) ActionTypes. To grant these actions, create a custom role that includes them and assign the custom role to the user. To learn how, see [Connect a Self-Managed Cluster to Atlas.](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-atlas.md#std-label-c2c-conn-onprem2atlas)

**Note:**

Write blocking only applies to users that do not have the [`bypassWriteBlockingMode`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-bypassWriteBlockingMode) ActionType. Users who have this ActionType can perform writes.

#### Permissible Reads

Read operations on the source cluster are always permitted.

When the [/progress](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) endpoint reports `canWrite` is `true`, the data on the source and destination clusters is consistent.

#### Permissible Writes

To see what state `mongosync` is in, call the [/progress](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) API endpoint. The `/progress` output includes a boolean value, `canWrite`.

- When `canWrite` is `true`, it is safe to write to the destination cluster.

- When `canWrite` is `false`, do not write to the destination cluster.

You can safely write to the source cluster while `mongosync` is syncing. Do not write to the destination cluster unless `canWrite` is `true`.

### Read and Write Concern

By default, `mongosync` sets the read concern level to [`"majority"`](https://www.mongodb.com/docs/manual/reference/read-concern-majority.md#mongodb-readconcern-readconcern.-majority-) for reads on the source cluster. For writes on the destination cluster, `mongosync` sets the write concern level to [`"majority"`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-majority-) with [j: true.](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-wc-j)

For more information on read and write concern configuration and behavior, see [Read Concern](https://www.mongodb.com/docs/manual/reference/read-concern.md#std-label-read-concern) and [Write Concern.](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-write-concern)

### Read Preference

`mongosync` requires the [`primary`](https://www.mongodb.com/docs/manual/core/read-preference.md#mongodb-readmode-primary) read preference when connecting to the source and destination clusters. For more information, see [Read Preference Options.](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#std-label-connections-read-preference)

### Legacy Index Handling

`mongosync` rewrites legacy index values, like `0` or an empty string, to `1` on the destination. `mongosync` also removes any invalid index options on the destination.

## Mid-sync Considerations

`mongosync` replication is different from replication of data within a [Replica Set](https://www.mongodb.com/docs/manual/replication/). `mongosync` [combines and reorders writes](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-c2c-behavior-consistency) from the source to destination cluster during the sync, and also [temporarily modifies](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-c2c-behavior-temporary-changes) various collection characteristics.

As a result, the destination is not guaranteed to match the source cluster at any point while the sync is still executing, including when the sync is paused. To ensure the destination and source clusters match before cutting over, call the [commit](https://www.mongodb.com/docs/mongosync/current/reference/api/commit.md#std-label-c2c-api-commit) endpoint.

The relationship between the source and destination cluster terminates upon commit, unless you use the [reverse](https://www.mongodb.com/docs/mongosync/current/reverse-sync.md#std-label-c2c-reverse-process) functionality. For information on mid-sync constraints, see [mongosync Migration Limitations](https://www.mongodb.com/docs/mongosync/current/reference/limitations.md#std-label-c2c-limitations) for limitations.

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

### Temporary Changes to Collection Characteristics

`mongosync` temporarily alters the following collection characteristics during synchronization. The original values are restored during the commit process.

| Change | Description |
| --- | --- |
| Unique Indexes | Unique indexes on the source cluster are synced as non-unique indexes on the destination cluster. |
| TTL Indexes | Synchronization sets `expireAfterSeconds` to the value of `MAX_INT` on the destination cluster. |
| Hidden Indexes | Synchronization replicates hidden indexes as non-hidden. |
| Write Blocking | `mongosync` manages write blocking internally based on your migration configuration. To learn more, see [Write Blocking.](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-c2c-write-blocking) |
| Capped Collections | Synchronization sets capped collections to the maximum allowable size. |
| Dummy Indexes | In some cases, synchronization may create dummy indexes on the destination to support writes on sharded or collated collections. |

### Rolling Index Builds

`mongosync` does not support [rolling index builds](https://www.mongodb.com/docs/manual/tutorial/build-indexes-on-replica-sets.md#std-label-index-building-replica-sets) during migration. To avoid building indexes in a rolling fashion during migration, use one of the following methods to ensure that your destination indexes match your source indexes:

- Build the index on the source before migration.

- Build the index on the source during migration with a [default index build.](https://www.mongodb.com/docs/manual/core/index-creation.md#std-label-index-creation-background)

- Build the index on the destination after migration.

### `mongosync` Metadata

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

## Destination Clusters

### Consistency

`mongosync` supports [eventual consistency](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-eventual-consistency) on the destination cluster. Read consistency is not guaranteed on the destination cluster until commit. Before committing, the source and destination clusters may differ at a given point in time. To learn more, see [Mid-sync Considerations.](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-behavior.md#std-label-mongosync-considerations)

While `mongosync` is syncing, `mongosync` may reorder or combine writes as it relays them from source to destination. For a given document, the total number of writes may differ between source and destination.

Transactions might not appear atomically on the destination cluster. Retryable writes may not be retryable on the destination cluster.

### Profiling

If profiling is enabled on a source database, MongoDB creates a special collection named `<db>.system.profile`. After synchronization is complete, Mongosync will not drop the `<db>.system.profile` collection from the destination even if the source database is dropped at a later time. The `<db>.system.profile` collection will not change the accuracy of user data on the destination.

### Views

If a database with views is dropped on the source, the destination may show an empty `system.views` collection in that database. The empty `system.views` collection will not change the accuracy of user data on the destination.

### System Collections

Mongosync does not replicate [system collections](https://www.mongodb.com/docs/manual/reference/system-collections.md#std-label-metadata-system-collections) to the destination cluster.

If you issue a [`dropDatabase`](https://www.mongodb.com/docs/manual/reference/command/dropDatabase.md#mongodb-dbcommand-dbcmd.dropDatabase) command on the source cluster, this change is not directly applied on the destination cluster. Instead, Mongosync drops user collections and views in the database on the destination cluster, but it does not drop system collections on that database.

For example, on the destination cluster:

- The drop operation does not affect a user-created [`system.js`](https://www.mongodb.com/docs/manual/reference/system-collections.md#mongodb-data--database-.system.js) collection.

- If you enable profiling, the [`system.profile`](https://www.mongodb.com/docs/manual/reference/system-collections.md#mongodb-data--database-.system.profile) collection remains.

- If you create views on the source cluster and then drop the database, replicating the drop removes the views, but leaves an empty [`system.views`](https://www.mongodb.com/docs/manual/reference/system-collections.md#mongodb-data--database-.system.views) collection.

In these cases, the replication of `dropDatabase` removes all user-created collections from the database, but leaves its system collections on the destination cluster.

### UUIDs

`mongosync` creates collections with new UUIDs (universally unique identifiers) on the destination cluster. There is no relationship between UUIDs on the source cluster and the destination cluster. If applications contain hard-coded UUIDs (which MongoDB does not recommend), you may need to update those applications before they work properly with the migrated cluster.

### Sorting

`mongosync` inserts documents on the destination cluster in an undefined order which does not preserve natural sort order from the source cluster. If applications depend on document order but don't have a defined sort method, you may need to update those applications to specify the expected sort order before the applications work properly with the migrated cluster.

### MongoDB Atlas Internal Databases

MongoDB Atlas and other cloud services store essential data in dedicated [internal databases](https://www.mongodb.com/docs/atlas/reference/internal-database.md#std-label-cloud-system-databases) within your cluster. These databases start with `__mdb_internal`. Starting in 1.18, `mongosync` ignores all databases that start with `__mdb_internal`.

## Performance

### Index Build Optimizations

**New in version 1.19**

#### Index Build Batch Sizes

If your source cluster runs MongoDB 6.0 or later, or you set `buildIndexes` to `afterDataCopy` or `excludeHashedAfterCopy` when running [`start`](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start), `mongosync` builds indexes on the destination cluster after data copy. It programmatically computes an appropriate batch size when calling [`createIndexes`](https://www.mongodb.com/docs/manual/reference/command/createIndexes.md#mongodb-dbcommand-dbcmd.createIndexes) to build indexes on destination clusters hosted on MongoDB Atlas. For non-Atlas clusters, `mongosync` uses a default batch size of 2.

Each batch is a single [`createIndexes`](https://www.mongodb.com/docs/manual/reference/command/createIndexes.md#mongodb-dbcommand-dbcmd.createIndexes) command containing indexes from one collection. A collection with more indexes than the batch size requires multiple batches.

You can find the computed batch size in the `mongosync` logs by searching for "`createIndexes batch size`".

To explicitly set a batch size for index builds, see the [`--createIndexesBatchSize`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--createIndexesBatchSize) configuration option.

#### Index Build Parallelism

`mongosync` automatically parallelizes index builds on Atlas destination clusters by concurrently issuing 12 [`createIndexes`](https://www.mongodb.com/docs/manual/reference/command/createIndexes.md#mongodb-dbcommand-dbcmd.createIndexes) commands and relying on the destination cluster's [`maxNumActiveUserIndexBuilds`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.maxNumActiveUserIndexBuilds) parameter to cap the number of concurrent `createIndexes` commands. Non-Atlas destination clusters with pre-existing data have serial index builds to avoid overwhelming the destination CPU. If you have a non-Atlas destination cluster and set `preExistingDestinationData` to `true` when you call the [`start`](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) endpoint, you cannot update index build parallelism.

To explicitly tune `mongosync`'s index build parallelism, adjust the [`maxNumActiveUserIndexBuilds`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.maxNumActiveUserIndexBuilds) setting on the destination cluster. Increasing this value improves overall index build speeds but raises CPU load on the destination. Monitor CPU utilization closely to avoid performance degradation and unintended auto-scaling events, which can occur when the cluster's CPU utilization exceeds [these limits.](https://www.mongodb.com/docs/atlas/cluster-autoscaling.md#std-label-cluster-autoscaling)

### Resilience

`mongosync` is resilient and able to handle non-fatal errors. Logs that contain the word "error" or "failure" do not indicate that `mongosync` is failing or corrupting data. For example, if a network error occurs, the `mongosync` log may contain the word "error' but `mongosync` is still able to complete the sync. In the case that a sync does not complete, `mongosync` writes a fatal log entry.

### Data Definition Language (DDL) Operations

Using DDL operations (operations that act on collections or databases such as [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) and [`db.dropDatabase()`](https://www.mongodb.com/docs/manual/reference/method/db.dropDatabase.md#mongodb-method-db.dropDatabase)) during sync increase the risk of migration failure and may negatively impact `mongosync` performance. For best performance, refrain from performing DDL operations on the source cluster while the sync is in progress.

For more information on DDL operations, see [Pending DDL Operations and Transactions.](https://www.mongodb.com/docs/manual/core/transactions-production-consideration.md#std-label-txn-prod-considerations-ddl)

### Network Latency

Network latency or long physical distances between migration components can negatively affect sync speed.

Latency between `mongosync` and destination shards

For each write operation on the source cluster, `mongosync` does one roundtrip to the destination server. `mongosync` also makes supporting requests for each batch of replicated write operations. The higher the latency, the slower the sync.

Latency between destination shards

`mongosync` runs operations and updates its own metadata in batches in a transaction on the destination cluster. This can result in cross-shard transactions, which may be more costly if the shards are far apart.

Latency between the nodes of any replica set on the source or destination cluster

`mongosync` uses [`"majority"`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-majority-) writes and [`"majority"`](https://www.mongodb.com/docs/manual/reference/read-concern-majority.md#mongodb-readconcern-readconcern.-majority-) reads, which require acknowledgement from multiple nodes in a replica set, including shard-backing replica sets. If the majority of these nodes aren't in the same region, there will be negative performance implications.

## Interruptions During Sync

The following considerations pertain to interruptions during the `mongosync` process.

### Errors and Crashes

If `mongosync` encounters an error or becomes unavailable during synchronization, or you can resume your `mongosync` operation from where it stopped. The `mongosync` binary is stateless and stores the metadata for a restart on the destination cluster.

To continue sync, restart `mongosync` once it becomes available again and use the same parameters as your interupted sync. Once you restart `mongosync`, the process resumes from where it stopped.

### Cluster Availability

If your source or destination cluster crashes unexpectedly, you can recover the migration without restarting from the beginning. After the cluster comes back online, restart the `mongosync` binary using the same connection string parameters from your original migration. `mongosync` reads its stored state from the destination cluster and automatically resumes the sync.

To verify that sync has resumed, call the [/progress](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) endpoint and confirm that `state` returns `RUNNING`.

**Warning:**

If the source cluster outage exceeds the [oplog window](https://www.mongodb.com/docs/mongosync/current/reference/oplog-sizing.md#std-label-c2c-oplog-sizing), `mongosync` cannot resume. You must [restart the migration](https://www.mongodb.com/docs/mongosync/current/reference/restart-mongosync.md#std-label-mongosync-restart-migration) from the beginning, which removes all migrated data from the destination cluster.

### Paused Sync

If `mongosync` is in the [PAUSED](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-states.md#std-label-c2c-state-paused) state, `mongosync` does not support the following actions:

- Upgrading the MongoDB version of the source or destination cluster

- Enabling and then disabling the balancer

You can upgrade `mongosync` while it is in the `PAUSED` state.

## Learn More

- [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)

- [Self-Managed to Atlas](https://www.mongodb.com/docs/mongosync/current/connecting/onprem-to-atlas.md#std-label-c2c-conn-onprem2atlas)

- [`mongosync` States](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-states.md#std-label-c2c-states)

- [`start`](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api)

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