diff --git a/source/includes/fact-mongosync-balancer.rst b/source/includes/fact-mongosync-balancer.rst index c408ef56b..fca039ea4 100644 --- a/source/includes/fact-mongosync-balancer.rst +++ b/source/includes/fact-mongosync-balancer.rst @@ -1,7 +1,31 @@ .. important:: - When the source or destination cluster is a sharded cluster, you must stop - the balancer on both clusters and not run the :dbcommand:`moveChunk` or - :dbcommand:`moveRange` commands for the duration of the migration. To stop - the balancer, run the :dbcommand:`balancerStop` command and wait for the - command to complete. + You must always disable the balancer on a sharded destination + cluster by using :dbcommand:`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 :ref:`namespace + filtering `, + you must disable the source cluster's balancer + by running the :dbcommand:`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 :ref:`disabling-balancer-filtered`. You can also fully disable + the source cluster's balancer. + + During migration, do not run the :dbcommand:`moveChunk` or + :dbcommand:`moveRange` commands. If you have enabled the source cluster's + balancer, but disabled it for collections within the namespace + filter, do not run :dbcommand:`shardCollection` on collections + within the namespace filter. If you run :dbcommand:`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. \ No newline at end of file diff --git a/source/reference/limitations.txt b/source/reference/limitations.txt index 4386e9d67..05aa3c1b0 100644 --- a/source/reference/limitations.txt +++ b/source/reference/limitations.txt @@ -124,16 +124,31 @@ Sharded Clusters To check for index inconsistencies, see :ref:`Find Inconsistent Indexes Across Shards `. -- You must stop the balancer on sharded source and destination clusters - for the entire lifetime of a migration. To stop the balancer, run the - :dbcommand:`balancerStop` command and wait for the command to - complete. - - .. note:: - - 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 :ref:`namespace + filtering `, + you must disable the source cluster's balancer + by running the :dbcommand:`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 :ref:`disabling-balancer-filtered`. You can also fully disable + the source cluster's balancer. + + You must always disable the balancer on a sharded destination + cluster by using :dbcommand:`balancerStop`. + +- If you have enabled the source cluster's + balancer, but disabled it for collections within the namespace + filter, do not run :dbcommand:`shardCollection` on collections + within the namespace filter. If you run :dbcommand:`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. - You must not run the :dbcommand:`moveChunk` and :dbcommand:`moveRange` commands on the source or destination clusters. diff --git a/source/reference/mongosync/mongosync-behavior.txt b/source/reference/mongosync/mongosync-behavior.txt index 11374aba6..6a567919e 100644 --- a/source/reference/mongosync/mongosync-behavior.txt +++ b/source/reference/mongosync/mongosync-behavior.txt @@ -102,6 +102,49 @@ preserve the source cluster's sharding configuration. .. include:: /includes/fact-mongosync-balancer.rst +.. _disabling-balancer-filtered: + +Disabling Balancer for Collections in Filtered Sync +''''''''''''''''''''''''''''''''''''''''''''''''''' + +If you are using a :ref:`namespace filter ` +and want to enable your source cluster's balancer for +collections outside the namespace filter, +follow these instructions before +you start ``mongosync``. + +.. procedure:: + :style: normal + + .. step:: Enable the balancer for the source cluster. + + Before starting ``mongosync`` with a :ref:`namespace filter + `, enable the balancer for the source cluster + by running the :method:`sh.startBalancer()` method in ``mongosh``. + + .. step:: Disable the balancer for each collection. + + Disable the balancer for each collection within the + namespace filter by running the :dbcommand:`setAllowMigrations` command: + + .. code-block:: javascript + + db.adminCommand( + { + setAllowMigrations: “.”, + 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 '''''''''''''''' @@ -131,7 +174,7 @@ primary shard to each database by means of a round-robin. .. warning:: - Running :dbcommand:`movePrimary` on the source or desintation cluster + Running :dbcommand:`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 :ref:`c2c-sharded-limitations`.