Limitations

General Limitations

• mongosync does not support in-place server version upgrades that change the major or minor version during a migration. mongosync does allow patch version upgrades. To learn more, see the server upgrade instructions.

• mongosync doesn't validate that the clusters or the environment are properly configured.

• Other clients must not write to the destination cluster while mongosync is running.

• If you want to start the commit process and you did not set enableUserWriteBlocking to "sourceAndDestination" when you used the start endpoint, you must prevent writes to the source cluster before you start the commit process.

• system.* collections aren't replicated.

• Documents that have dollar ($) prefixed field names aren't supported. See Field Names with Periods and Dollar Signs.

• Serverless clusters aren't supported.

• A MongoDB Shared Tier isn't supported.

• Queryable Encryption isn't supported.

• You cannot sync a collection that has a unique index and a non-unique index defined on the same field(s).

• Before you attempt to run mongosync with an M10+ Atlas cluster, disable the Require Indexes for All Queries option.

• mongosync doesn't sync users or roles.

• mongosync does not replicate applyOps operations made on the source cluster during sync to the destination cluster.

• mongosync must read from the source cluster using the primary read preference.

• mongosync does not support source or destination clusters that are currently upgrading MongoDB versions.

• mongosync does not support syncing Atlas Search Indexes.

• mongosync only supports clusters that use the WiredTiger storage engine.

• You can't sync a collection with any documents that have an empty timestamp, such as Timestamp(0,0) on pre-6.0 source clusters.

• mongosync does not support documents with duplicate field names. For details, see MongoDB does not support duplicate field names.

MongoDB Community Edition

MongoDB does not test Mongosync with Community builds and in most cases, MongoDB does not offer support for Mongosync with Community deployments. If you would like to use Mongosync with MongoDB Community Edition, contact a MongoDB sales representative to discuss requirements and individualized options.

Unsupported Collection Types

• Time-series collections aren't supported.

• Clustered collections with expireAfterSeconds set aren't supported.

Sharded Clusters

• mongosync doesn't support sync from a sharded cluster to a replica set.

• mongosync doesn't support sync to a sharded cluster topology with one or more arbiters.

• mongosync doesn't support sync to or from global clusters.

• Sync from a replica set to a sharded cluster has the following limitations:

  • mongosync allows users to rename collections that the sharding.shardingEntries option includes during sync with some limitations. For details, see Renaming During Sync.

  • If you use the sharding.createSupportingIndexes option, the indexes are automatically created on the destination cluster during the sync. You cannot create these indexes afterwards on the source cluster.

  • If you want to create an index to support shard keys manually, you must create the index before mongosync starts or after the migration is complete and mongosync has stopped.

• Within a collection, the _id field must be unique across all of the shards in the cluster. See Sharded Clusters and Unique Indexes for more details.

• The movePrimary command cannot be used to reassign the primary shard while syncing.

• There is no replication for zone configuration. mongosync replicates data, it doesn't inherit zones.

• Shards cannot be added or removed while syncing.

• mongosync only syncs indexes that exist on all shards.

• mongosync only syncs indexes that have consistent index specifications on all shards.

  Note

  To check for index inconsistencies, see Find Inconsistent Indexes Across Shards.

• If the source or destination cluster is a sharded cluster and you are not running mongosync with namespace filtering, you must disable the source cluster's balancer by running the 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. You can also fully disable the source cluster's balancer.

  You must always disable the balancer on a sharded destination cluster by using balancerStop.

• If you have enabled the source cluster's balancer, but disabled it for collections within the namespace filter, do not run shardCollection on collections within the namespace filter. If you run 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.

• mongosync doesn't support running the command transitionFromDedicatedConfigServer during execution.

• You must not run the moveChunk and moveRange commands on the source or destination clusters.

• The shard key cannot be refined while syncing.

• The reshardCollection operations from the source cluster are not supported during sync.

• The maximum number of indexes per sharded collection is 63, which is one less than the default limit of 64.

• mongosync only supports syncing sharded collections that have default collation settings.

• mongosync errors on indexes that are inconsistent or missing on some data-bearing shards.

• mongosync fails if there is a balancing window configured on the source or destination cluster.

Reversing

• If the old source has unique indexes which are partially distributed across shards, reversing may cause failures. Ensure that unique indexes exist on all shards before reversing.

• The source and destination clusters must have the same number of shards. You cannot reverse sync when the clusters have different topologies or major versions.

• In order to reverse direction, mongosync requires that all unique indexes on the source cluster (except for _id) do not have legacy unique index keys.

Multiple Clusters

• mongosync does not support syncing multiple source clusters to one destination cluster.

• One cluster cannot simultaneously be a source cluster in one mongosync instance and a destination cluster in another mongosync instance.

Filtered Sync

• Filtering is not supported with reversible sync.

• The destination cluster must not contain user data prior to starting.

• The destination cluster must not contain the mongosync_reserved_for_internal_use system database prior to starting.

• You cannot modify a filter that is in use. To create a new filter, see: Replace an Existing Filter.

• You can only rename collections in certain situations. For more details see: Adding and Renaming Collections.

• If a filter includes a view but not the base collection, only the view metadata syncs to the destination cluster. To include the view documents, you must also sync the base collection.

• You cannot specify system collections or system databases in a filter.

• To use the $out aggregation stage or the mapReduce command (when set to create or replace a collection) with filtering, you must configure the filter to use the entire database. You cannot limit the filter to collections within the database.

  For more information, see Filtering with mapReduce and $out.

• Filtering does not support dual write blocking. You can use destination-only write-blocking.

Capped Collections

Starting in 1.3.0, Mongosync supports capped collections with some limitations.

• convertToCapped is not supported. If you run convertToCapped, mongosync exits with an error.

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

System Collections

Mongosync does not replicate system collections to the destination cluster.

If you issue a 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 collection.

• If you enable profiling, the 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 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.

Rolling Index Builds

mongosync does not support rolling index builds 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.

• Build the index on the destination after migration.

Embedded Verifier

Starting in 1.9, mongosync can use an embedded verifier to confirm the successful sync of collections from the source cluster to the destination cluster.

Persistent Query Settings

mongosync doesn't migrate Persistent Query Settings (PQS), which were introduced in MongoDB 8.0. If your source cluster uses PQS, you must migrate them manually.

Pre-6.0 Migrations

Starting in 1.10, mongosync supports migrations from source clusters running MongoDB server versions older than 6.0. For information on supported migration paths, see MongoDB Server Version Compatibility.

The following limitations apply to pre-6.0 migrations:

• The source cluster cannot have orphaned documents. To clean up any orphaned documents, run the cleanupOrphaned command on the mongod instances on every shard's primary node on their source cluster. Wait for this command to complete with a status {ok:1} before starting the migration.

• Writes that produce DDL events cannot occur on the source cluster during the migration. The following events cannot occur:

  • collMod

  • create

  • createIndexes

  • drop

  • dropDatabase

  • dropIndexes

  • refineCollectionShardKey

  • rename

  • reshardCollection

  • shardCollection

  This includes operations that may create new collections such as mapReduce, $out, and $merge. This also includes collections created implicitly from inserts. Only writes that produce CRUD events can occur during the migration.

  Note

  Writes that produce DDL events on source collections outside of the namespace filter are allowed.

• geoHaystack indexes are not supported.

• /reverse endpoint is not supported. You can't enable the reversible option in the /start request.

• You can't set the enableUserWriteBlocking option to "sourceAndDestination" in the /start request, so dual write-blocking is not supported. Destination-only write-blocking is supported. Ensure that no writes are made to the source cluster after you call the /commit endpoint.

• You can't enable the createSupportingIndexes sharding parameter. Instead, create an index to support your shard key on the source cluster.

• If there are any indexes with inconsistent specs or that are missing on one or more shards, mongosync returns an error. To check for index inconsistencies, see Find Inconsistent Indexes Across Shards.