DOCSP-7707 remove manual flushRouterConfig for most cases

Author: andf-mongodb

source/includes/warning-dropDatabase-shardedCluster.rst

@@ -1,34 +1,34 @@
-.. warning::
-
-   Starting in MongoDB 4.2:
-      If you drop a database and create a new database with the same name, you
-      must either:
-      
-      - Restart all :binary:`~bin.mongos` instances and all
-        :binary:`~bin.mongod` shard members (including the secondary
-        members);
-      
-      - Use the :dbcommand:`flushRouterConfig` command on all
-        :binary:`~bin.mongos` instances and all :binary:`~bin.mongod`
-        shard members (including the secondary members) before reading
-        or writing to that database.
-      
-      This ensures that the :binary:`~bin.mongos` and shard instances
-      refresh their metadata cache, including the location of the
-      :ref:`primary shard <primary-shard>` for the new database.
-      
-      Otherwise, the you may miss data on reads, and may not write data to
-      the correct shard. To recover, you must manually intervene.
-      
-   In MongoDB 4.0 and earlier:      
-      If you drop a database and create a new database with the same name, you
-      must either restart all :binary:`~bin.mongos` instances, or use the
-      :dbcommand:`flushRouterConfig` command on all :binary:`~bin.mongos`
-      instances before reading or writing to that database. This 
-      ensures that the :binary:`~bin.mongos` instances refresh their
-      metadata cache, including the location of the :ref:`primary shard
-      <primary-shard>` for the new database. 
-      
-      Otherwise, the you may miss data on reads, and may not write data to
-      the correct shard. To recover, you must manually intervene.
-      
+For MongoDB 4.2 and previous, when executing the
+:dbcommand:`dropDatabase` command, you must perform the following
+additional steps if you intend to create a new database with the same
+name as the dropped database.
+
+.. note::
+
+   MongoDB 4.4 does not require these additional steps when dropping and
+   recreating a database with the same name.
+
+- For **MongoDB 4.2**, you must either:
+
+  - Restart all :binary:`~bin.mongos` instances and all
+    :binary:`~bin.mongod` shard members (including the secondary
+    members);
+
+  - Use the :dbcommand:`flushRouterConfig` command on all
+    :binary:`~bin.mongos` instances and all :binary:`~bin.mongod`
+    shard members (including the secondary members) before reading
+    or writing to that database.
+
+- For **MongoDB 4.0 and earlier**, you must either:
+
+  - Restart all :binary:`~bin.mongos` instances;
+
+  - Use the :dbcommand:`flushRouterConfig` command on all
+    :binary:`~bin.mongos` instances before reading or writing to that
+    database.
+
+These steps ensure that all cluster nodes refresh their metadata cache,
+which includes the location of the :ref:`primary shard<primary-shard>`
+for the new database. Otherwise, you may miss data on reads, and may not
+write data to the correct shard. To recover, you must manually
+intervene.

source/includes/warning-movePrimary.rst

@@ -1,32 +1,33 @@
-.. warning::
-
-
-   Starting in MongoDB 4.2:
-      If you use the :dbcommand:`movePrimary` command to move
-      *unsharded* collections, you must either:
-   
-      - Restart all :binary:`~bin.mongos` instances **and** all
-        :binary:`~bin.mongod` shard members (including the secondary
-        members);
-   
-      - Use the :dbcommand:`flushRouterConfig` command on all
-        :binary:`~bin.mongos` instances and all :binary:`~bin.mongod`
-        shard members (including the secondary members) before reading
-        or writing any data to any *unsharded* collections that were
-        moved.
-   
-      Otherwise, you may miss data on reads, and may not write data to
-      the correct shard. To recover, you must manually intervene.
-
-   In MongoDB 4.0 and earlier:
-      If you use the :dbcommand:`movePrimary` command to move
-      *unsharded* collections, you must either:
-      
-      - Restart all :binary:`~bin.mongos` instances;
-        
-      - Use the :dbcommand:`flushRouterConfig` command on all
-        :binary:`~bin.mongos` instances before reading or writing any
-        data to any unsharded collections that were moved.
-
-      Otherwise, you may miss data on reads, and may not write data to
-      the correct shard. To recover, you must manually intervene.
+For MongoDB 4.2 and previous, if using the :dbcommand:`movePrimary`
+command on a database that contains an *unsharded* collection, you
+must perform the following additional steps.
+
+.. note::
+
+   MongoDB 4.4 does not require these additional steps when moving
+   databases that contain unsharded collections.
+
+- For **MongoDB 4.2**, you must either:
+
+  - Restart all :binary:`~bin.mongos` instances **and** all
+    :binary:`~bin.mongod` shard members (including the secondary
+    members);
+
+  - Use the :dbcommand:`flushRouterConfig` command on all
+    :binary:`~bin.mongos` instances and all :binary:`~bin.mongod`
+    shard members (including the secondary members) before reading
+    or writing any data to any unsharded collections that were
+    moved.
+
+- For **MongoDB 4.0 and earlier**, you must either:
+
+  - Restart all :binary:`~bin.mongos` instances;
+
+  - Use the :dbcommand:`flushRouterConfig` command on all
+    :binary:`~bin.mongos` instances before reading or writing any data
+    to any unsharded collections that were moved.
+
+These steps ensure that all cluster nodes refresh their metadata cache,
+which includes the location of the :ref:`primary shard<primary-shard>`.
+Otherwise, you may miss data on reads, and may not write data to the
+correct shard. To recover, you must manually intervene.

source/reference/command/flushRouterConfig.txt

@@ -10,60 +10,88 @@ flushRouterConfig
    :depth: 1
    :class: singlecol
 
+Definition
+----------
+
 .. dbcommand:: flushRouterConfig
 
-   :dbcommand:`flushRouterConfig` clears the cached routing table. Use
-   this command to force a refresh of the routing table cache. In most
-   cases, this happens automatically. You should only need to run
-   :dbcommand:`flushRouterConfig` after :dbcommand:`movePrimary` has
-   been run or after manually clearing the ``jumbo`` chunk flag.
+   :dbcommand:`flushRouterConfig` marks the cached routing table for a 
+   sharded cluster as stale, causing the next operation that requests
+   the routing table to refresh the cache. Management of the routing
+   table cache is generally handled automatically by the cluster. You
+   should only need to run the :dbcommand:`flushRouterConfig` command
+   manually in specific instances, as indicated under
+   :ref:`flushrouterconfig-considerations`.
+
+.. note::
+
+   **Starting in MongoDB 4.4,** running :dbcommand:`flushRouterConfig`
+   is no longer required after executing the :dbcommand:`movePrimary` or
+   :dbcommand:`dropDatabase` commands. These two commands now
+   automatically refresh a sharded cluster's routing table as needed
+   when run.
+
+Syntax
+------
+
+Starting in MongoDB 4.0.6 (and 3.6.11), the
+:dbcommand:`flushRouterConfig` is available on both
+:binary:`~bin.mongos` and :binary:`~bin.mongod` instances, and has the
+following syntax:  
+
+- Flush the cache for a specified collection when passed in a
+  collection namespace parameter:
 
-   - **Starting in MongoDB 4.0.6 (and 3.6.11),**
-     :dbcommand:`flushRouterConfig` is available on both
-     :binary:`~bin.mongos` instances and :binary:`~bin.mongod`
-     instances and can:
+  .. code-block:: javascript
 
-     - Flush the cache for a specified collection when passed in a
-       collection namespace parameter:
+     db.adminCommand({ flushRouterConfig: "<db.collection>" } )
 
-       .. code-block:: javascript
+- Flush the cache for a specified database and all of its collections
+  when passed in a database namespace parameter:
 
-          db.adminCommand({ flushRouterConfig: "<db.collection>" } )
+  .. code-block:: javascript
 
-     - Flush the cache for a specified database and its collections
-       when passed in a database namespace parameter:
+     db.adminCommand({ flushRouterConfig: "<db>" } ) 
 
-       .. code-block:: javascript
+- Flush the cache for all databases and their collections when run
+  without a parameter or passed in a non-string scalar value
+  (e.g. ``1``):
 
-          db.adminCommand({ flushRouterConfig: "<db>" } ) 
+  .. code-block:: javascript
 
-     - Flush the cache for all databases and their collections when run
-       without a parameter or passed in a non-string scalar value (e.g. ``1``):
+     db.adminCommand("flushRouterConfig")
+     db.adminCommand( { flushRouterConfig: 1 } )
 
-       .. code-block:: javascript
+.. note::
 
-          db.adminCommand("flushRouterConfig")
-          db.adminCommand( { flushRouterConfig: 1 } )
+   **In MongoDB 4.0.5 and earlier (and 3.6.10 and earlier)**,
+   :dbcommand:`flushRouterConfig` is only available for
+   :binary:`~bin.mongos` instances and can only flush the cache for all
+   databases and their collections:
 
-   - **In MongoDB 4.0.5 and earlier (and 3.6.10 and earlier)**,
-     :dbcommand:`flushRouterConfig` is only available for
-     :binary:`~bin.mongos` instances and can flush the cache for all
-     databases and their collections:
+   .. code-block:: javascript
 
-     .. code-block:: javascript
+      db.adminCommand("flushRouterConfig")
+      db.adminCommand( { flushRouterConfig: 1 } )
 
-        db.adminCommand("flushRouterConfig")
-        db.adminCommand( { flushRouterConfig: 1 } )
+.. _flushrouterconfig-considerations:
 
 Considerations
 --------------
 
-You should only need to run :dbcommand:`flushRouterConfig` after
-:dbcommand:`movePrimary` has been run or after manually clearing the
-``jumbo`` chunk flag.
+Generally, a sharded cluster's routing table is automatically refreshed
+as needed as part of normal operation. However, you should manually
+issue the :dbcommand:`flushRouterConfig` command in the following
+instances:
 
-.. seealso::
+- If running MongoDB 4.2 or earlier, after executing the
+  :dbcommand:`movePrimary` or :dbcommand:`dropDatabase` commands.
 
-   - :ref:`movePrimary Considerations <movePrimary-consideration>`
+- If running MongoDB 4.2.2 or earlier (or 4.0.14 or earlier), after
+  manually clearing the ``jumbo`` flag from a chunk that could not be
+  split (i.e. an *indivisible chunk*). See
+  :doc:`/tutorial/clear-jumbo-flag` for more information.
 
-   - :doc:`/tutorial/clear-jumbo-flag`
+- Before running the :method:`db.collection.getShardDistribution()`
+  command. This ensures that the command returns the most up-to-date
+  information.

source/release-notes/4.4.txt

@@ -536,6 +536,17 @@ MongoDB 4.4 adds the following parameters for controlling this behavior:
     to the :binary:`~bin.mongos` are allowed regardless of established
     connection pool size.
 
+Improved Routing Table Updates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Running :dbcommand:`flushRouterConfig` is no longer required after
+executing the :dbcommand:`movePrimary` or :dbcommand:`dropDatabase`
+commands. These two commands now automatically refresh a sharded
+cluster's routing table as needed when run. Manually issuing the
+:dbcommand:`flushRouterConfig` command is still recommended in the cases
+described under
+:ref:`flushRouterConfig Considerations<flushrouterconfig-considerations>`.
+
 General Sharded Clusters Improvements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/tutorial/clear-jumbo-flag.txt

@@ -78,7 +78,7 @@ You can manually clear the flag using the following steps.
 
    .. tabs::
 
-      .. tab:: For MongoDB v4.2.3+ (4.0.15+)
+      .. tab:: MongoDB 4.2.3 and later (4.0.15 and later)
          :tabid: clear-flag-command
 
          Starting in version 4.2.3 and 4.0.15, MongoDB provides the
@@ -93,7 +93,7 @@ You can manually clear the flag using the following steps.
          .. include:: /includes/steps/clear-jumbo-flag-command.rst
 
 
-      .. tab:: For MongoDB v4.2.2 and earlier (4.0.14 and earlier)
+      .. tab:: MongoDB 4.2.2 and earlier (4.0.14 and earlier)
          :tabid: clear-flag-manual
 
 

source/tutorial/remove-shards-from-cluster.txt

@@ -246,6 +246,9 @@ resemble the following:
    }
    }
 
+Using ``movePrimary`` To Move Unsharded Collections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. include:: /includes/warning-movePrimary.rst 
 
 .. _remove-shard-finalize-migration: