DOCSP-24455 BACKPORT (#2668)

* DOCSP-24455 BACKPORT

* Version references

* Missing reference

Author: Dave Cuthbert

source/includes/reference/compact-methods-list.rst

@@ -0,0 +1,9 @@
+``compact`` blocks these operations:
+
+- :method:`db.collection.drop()`
+- :method:`db.collection.createIndex()`
+- :method:`db.collection.createIndexes()`
+- :method:`db.collection.dropIndex()`
+- :method:`db.collection.dropIndexes()`
+- :dbcommand:`collMod`
+

source/reference/command/compact.txt

@@ -40,27 +40,21 @@ Definition
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80
-   
+
       * - Field
-   
         - Type
-   
         - Description
-   
+
       * - ``compact``
-   
         - string
-   
         - The name of the collection.
-          
-          
-   
+
       * - ``force``
-   
         - flag
-   
         - .. versionchanged:: 4.4 
-        
+       
+          .. _compact-force-option:
+
           Optional. Starting in v4.4, if specified, forces 
           :dbcommand:`compact` to run on the :term:`primary` in 
           a :term:`replica set`. Before v4.4, this boolean field 
@@ -69,19 +63,15 @@ Definition
           returned an error when run on a :term:`primary` if the 
           value was ``false``, because the command blocked all other 
           operations.
-          
+         
           Starting in v4.4, :dbcommand:`compact` does not block 
           :ref:`crud` on the database it is compacting. 
-          
+         
       * - ``comment``
-
         - any
-
         - .. include:: /includes/extracts/comment-content.rst
-       
           .. versionadded:: 4.4   
 
-
 .. warning:: Always have an up-to-date backup before performing server
    maintenance such as the :dbcommand:`compact` operation.
 
@@ -96,30 +86,6 @@ action on the target collection. The :authrole:`dbAdmin` role provides
 the required privileges for running :dbcommand:`compact` against
 non-system collections. 
 
-For :ref:`system collections <metadata-system-collections>`, create a 
-custom role that grants the :authaction:`compact` action on the system 
-collection. You can then grant that role to a new or existing user and 
-authenticate as that user to perform the :dbcommand:`compact` command. 
-For example, the following operations create a custom role that grants 
-the :authaction:`compact` action against specified database and
-collection:
-
-.. code-block:: javascript
-
-   use admin
-   db.createRole(
-      {
-         role: "myCustomCompactRole",
-         privileges: [
-            {
-               resource: { "db" : "<database>" , "collection" : "<collection>" },
-               actions: [ "compact" ]
-            }
-         ],
-         roles: []
-      }
-   )
-
 For more information on configuring the ``resource`` document, see 
 :ref:`resource-document`.
 
@@ -156,28 +122,34 @@ Behavior
 Blocking
 ~~~~~~~~
 
-.. versionchanged:: 4.4 
+Blocking behavior is version specific. 
 
-Starting in v4.4, on :ref:`WiredTiger <storage-wiredtiger>`, 
-:dbcommand:`compact` only blocks the following metadata operations: 
+.. list-table::
 
-- :method:`db.collection.drop`
-- :method:`db.collection.createIndex` and 
-  :method:`db.collection.createIndexes`
-- :method:`db.collection.dropIndex` and 
-  :method:`db.collection.dropIndexes`
+   * - Version
+     - Blocking Behavior
 
-:dbcommand:`compact` does not block :ref:`crud` for the database it is 
-currently operating on. 
+   * - Pre 4.4
+     - ``compact`` blocks all read and write activity.
 
-Before v4.4, :dbcommand:`compact` blocked all operations for the 
-database it was compacting, including :ref:`crud`, and was therefore 
-recommended for use only during scheduled maintenance periods. Starting in 
-v4.4, the :dbcommand:`compact` command is appropriate for use at any time.
+   * - 4.4
+     - - .. include:: /includes/reference/compact-methods-list.rst
+       - All other operations are permitted.
 
-You may view the intermediate progress either by viewing the
-:binary:`~bin.mongod` log file or by running the 
-:method:`db.currentOp()` in another shell instance.
+   * - Post 4.4.17
+     - - .. include:: /includes/reference/compact-methods-list.rst
+       - All other operations are permitted.
+       - The :ref:`locking order <faq-concurrency-locking>` changes.
+
+To run ``compact`` in a replica set, see
+:ref:`compact-cmd-replica-sets` for additional considerations.
+
+Monitoring Progress
+~~~~~~~~~~~~~~~~~~~
+
+To check the ``compact`` operation's progress, monitor the
+:binary:`~bin.mongod` log file or run :method:`db.currentOp()`
+from another shell instance.
 
 Operation Termination
 ~~~~~~~~~~~~~~~~~~~~~
@@ -204,45 +176,91 @@ Disk Space
 To see how the storage space changes for the collection, run the
 :dbcommand:`collStats` command before and after compaction.
 
-On :ref:`WiredTiger <storage-wiredtiger>`, :dbcommand:`compact` attempts to
-reduce the required storage space for data and indexes in a collection, releasing
-unneeded disk space to the operating system. The effectiveness of this operation
-is workload dependent and no disk space may be recovered. This command is useful
-if you have removed a large amount of data from the collection, and do not plan
-to replace it.
+On :ref:`WiredTiger <storage-wiredtiger>`, :dbcommand:`compact` attempts
+to reduce the required storage space for data and indexes in a
+collection, releasing unneeded disk space to the operating system. The
+effectiveness of this operation is workload dependent and no disk space
+may be recovered. This command is useful if you have removed a large
+amount of data from the collection, and do not plan to replace it.
 
-:dbcommand:`compact` may require additional disk space to run on WiredTiger databases.
+:dbcommand:`compact` may require additional disk space to run on
+WiredTiger databases.
 
 .. _compact-cmd-replica-sets:
 
 Replica Sets
 ~~~~~~~~~~~~
 
-:dbcommand:`compact` commands do not replicate to secondaries in a
-:term:`replica set`.
+You can use ``compact`` on collections and indexes that are stored in a
+replica set, however there are some important considerations:
+
+- The primary node does not replicate the ``compact`` command to the
+  secondaries.
+- The ``compact`` command blocks writes while it runs.
+- You should run ``compact`` on secondary nodes whenever possible. If
+  you cannot run ``compact`` on secondaries, see the :ref:`force 
+  <compact-force-option>` option.
+- Starting in MongoDB 4.4.17:
+
+  - A secondary node can replicate while ``compact`` is running.
+  - Reads are permitted.
+
+To run ``compact`` on a cluster
+
+.. procedure::
+   :style: connected
+
+   .. step:: Compact the secondary nodes.
+
+      Run ``compact`` on one of the secondary nodes. When ``compact``
+      finishes, repeat the operation on each of the remaining
+      secondaries in turn.
+
+   .. step:: Reassign the primary node.
+    
+      To step down the current primary and trigger an election, use the
+      :method:`rs.stepDown()` method. To nominate a particular secondary
+      node, :ref:`adjust the member priority
+      <replica-set-adjust-priority>`.
+
+   .. step:: Compact the old primary.
+
+      After stepping down, the old primary node becomes a secondary
+      node. Run ``compact`` on the old primary node.
+
+Version Specific Considerations for Secondary Nodes
+```````````````````````````````````````````````````
+
+Blocking behavior on secondary nodes is version specific.
+
+.. list-table::
+
+   * - Version
+     - Blocking Behavior
 
-- Compact each member separately.
+   * - Pre 4.4
+     - - ``compact`` blocks all read and write activity.
+       - No replication possible.
+       - Secondary node is in :replstate:`RECOVERING` state.
 
-- Ideally run :dbcommand:`compact` on a secondary. See option
-  ``force`` above for information regarding compacting the primary.
+   * - 4.4
+     - - ``compact`` blocks all write activity.
+       - No replication possible.
+       - Reads not permitted.
 
-- Starting in MongoDB 4.4.9 (and 4.2.18): a secondary is
-  not available when :dbcommand:`compact` is running. The secondary does
-  not enter the :replstate:`RECOVERING` state.
+   * - Post 4.4.17
+     - - ``compact`` blocks all write activity.
+       - No replication possible.
+       - Reads permitted.  
 
-- For previous MongoDB versions: on secondaries, :dbcommand:`compact`
-  forces the secondary to enter the :replstate:`RECOVERING` state. Read
-  operations issued to an instance in the :replstate:`RECOVERING` state
-  will fail. This prevents clients from reading during the operation.
-  When the operation completes, the secondary returns to
-  :replstate:`SECONDARY` state.
+When ``compact`` completes, the secondary returns to the
+:replstate:`SECONDARY` state.
 
-See :doc:`/reference/replica-states/` for more information about replica
-set member states.
+For more information about replica set member states, see
+See :ref:`replica-set-member-states`.
 
-See :doc:`/tutorial/perform-maintence-on-replica-set-members` for an
-example replica set maintenance procedure to maximize availability
-during maintenance operations.
+For replica set maintenance and availability, see
+:ref:`perform-maint-on-replica-set`.
 
 Sharded Clusters
 ~~~~~~~~~~~~~~~~

source/reference/replica-states.txt

@@ -1,3 +1,5 @@
+.. _replica-set-member-states:
+
 =========================
 Replica Set Member States
 =========================

source/tutorial/adjust-replica-set-member-priority.txt

@@ -1,3 +1,5 @@
+.. _replica-set-adjust-priority:
+
 ======================================
 Adjust Priority for Replica Set Member
 ======================================

source/tutorial/perform-maintence-on-replica-set-members.txt

@@ -1,3 +1,5 @@
+.. _perform-maint-on-replica-set:
+
 ==========================================
 Perform Maintenance on Replica Set Members
 ==========================================