DOCS-14979 adds setAllowMigrations command (#239)

* adds setAllowMigrations command

* updates 5.2 Release Notes

* review

* adds refs for sharding-chunk-migration-automatic and sharding-chunk-migration-manual

* updates nav and release notes

* updates release notes spacing

Author: jmd-mongo

source/core/sharding-data-partitioning.txt

@@ -167,10 +167,14 @@ MongoDB migrates chunks in a :term:`sharded cluster` to distribute the
 chunks of a sharded collection evenly among shards. Migrations may be
 either:
 
+.. _sharding-chunk-migration-manual:
+
 - Manual. Only use manual migration in limited cases, such as
   to distribute data during bulk inserts. See :doc:`Migrating Chunks
   Manually </tutorial/migrate-chunks-in-sharded-cluster>` for more details.
 
+.. _sharding-chunk-migration-automatic:
+
 - Automatic. The :ref:`balancer <sharding-balancing>` process
   automatically migrates chunks when there is an uneven distribution of
   a sharded collection's chunks across the shards. See :ref:`Migration

source/reference/command/nav-sharding.txt

@@ -140,6 +140,12 @@ Sharding Commands
 
        .. versionadded:: 5.0
 
+   * - :dbcommand:`setAllowMigrations`
+
+     - Prevents the start of new :ref:`automatic migrations <sharding-chunk-migration-automatic>` on a 
+       collection, prevents in-flight :ref:`manual migrations <sharding-chunk-migration-manual>` from 
+       committing, and excludes the collection from new balancer rounds.
+
    * - :dbcommand:`setShardVersion`
 
      - Internal command to sets the :term:`config server <config database>` version.
@@ -204,6 +210,7 @@ Sharding Commands
    /reference/command/removeShard
    /reference/command/removeShardFromZone
    /reference/command/reshardCollection
+   /reference/command/setAllowMigrations
    /reference/command/setShardVersion
    /reference/command/shardCollection
    /reference/command/shardingState

source/reference/command/setAllowMigrations.txt

@@ -0,0 +1,90 @@
+==================
+setAllowMigrations
+==================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. dbcommand:: setAllowMigrations
+
+   Prevents the start of new :ref:`automatic migrations 
+   <sharding-chunk-migration-automatic>` on a collection, prevents 
+   in-flight :ref:`manual migrations <sharding-chunk-migration-manual>` 
+   from committing, and excludes the collection from new balancer 
+   rounds.
+
+   The command has the following syntax:
+
+   .. code-block:: javascript
+
+      db.adminCommand( {
+        setAllowMigrations: "<db>.<collection>", 
+        allowMigrations: <true|false>
+      } )
+
+   The command takes the following parameters:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 20 60
+
+      * - Field
+        - Type
+        - Description
+
+      * - :ref:`setAllowMigrations <setAllowMigrations-cmd-coll>`
+
+        - ``string``
+        
+        - .. _setAllowMigrations-cmd-coll:
+          
+          The collection to modify.
+
+      * - :ref:`allowMigrations <setAllowMigrations-cmd-flag>`
+
+        - ``boolean``
+
+        - .. _setAllowMigrations-cmd-flag:
+        
+          If ``false``:
+
+          - MongoDB prevents new :ref:`automatic migrations 
+            <sharding-chunk-migration-automatic>` on the collection
+          - in-flight :ref:`manual migrations 
+            <sharding-chunk-migration-manual>` will not be committed
+          - the collection will be excluded from new balancer rounds
+
+          If ``true``: 
+          
+          - MongoDB allows new :ref:`automatic migrations 
+            <sharding-chunk-migration-automatic>` on the collection
+          - in-flight :ref:`manual migrations 
+            <sharding-chunk-migration-manual>` will be committed
+          - the collection will be included in new balancer rounds
+
+Behavior
+--------
+
+:dbcommand:`setAllowMigration` requires the same privileges as 
+:authaction:`moveChunk`.
+
+Example
+-------
+
+This operation prevents migrations on the ``store.inventory``
+collection:
+
+.. code-block:: javascript
+
+   db.adminCommand( {
+      setAllowMigrations: "store.inventory",
+      allowMigrations: false
+   } )

source/release-notes/5.2.txt

@@ -120,6 +120,17 @@ Starting in MongoDB 5.2, the
 :ref:`default chunk size <sharding-chunk-size>` is 128 megabytes. In 
 earlier versions of MongoDB, the default chunk size is 64 megabytes.
 
+Prevent Migrations on a Sharded Collection with ``setAllowMigrations``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 5.2, the :dbcommand:`setAllowMigrations` command:
+
+- Prevents the start of new :ref:`automatic migrations 
+  <sharding-chunk-migration-automatic>` on a collection
+- Prevents in-flight :ref:`manual migrations 
+  <sharding-chunk-migration-manual>` from committing
+- Excludes the collection from new balancer rounds
+
 .. _5.2-rel-notes-general:
 
 General Improvements