DOCSP-10113 Quiesce mode for short running operations

Author: jason-price-mongodb

source/includes/quiesce-period.rst

@@ -0,0 +1,44 @@
+Starting in MongoDB 5.0, :binary:`~bin.mongod` and :binary:`~bin.mongos`
+enter a quiesce period to allow any ongoing database operations to
+complete before shutting down.
+
+If a :binary:`~bin.mongod` :term:`primary` receives a shut down request,
+the primary:
+
+#. Attempts to step down to a :term:`secondary`.
+
+   If the step down fails and a:
+
+   - :dbcommand:`shutdown` or :method:`db.shutdownServer()` command
+     was run, :binary:`~bin.mongod` only continues the shut down steps
+     if the |force| field is true, or a
+   
+   - ``SIGTERM`` signal was sent to :binary:`~bin.mongod`,
+     :binary:`~bin.mongod` always continues the shut down steps.
+
+#. Enters the quiesce period.
+
+#. Ends any remaining database operations.
+
+#. Shuts down.
+
+For a :binary:`~bin.mongod` :term:`secondary` or :binary:`~bin.mongos`
+shut down request, the quiesce period is entered after a shut down was
+requested.
+
+The quiesce period is specified by the:
+
+- |timeout| field if a :dbcommand:`shutdown` or
+  :method:`db.shutdownServer()` command was run, or
+
+- :parameter:`shutdownTimeoutMillisForSignaledShutdown` server
+  parameter if a ``SIGTERM`` signal was sent to :binary:`~bin.mongod`,
+  or
+  
+- :parameter:`mongosShutdownTimeoutMillisForSignaledShutdown` server
+  parameter if a ``SIGTERM`` signal was sent to :binary:`~bin.mongos`.
+
+The |timeout| field defaults to ``15`` seconds in MongoDB 5.0.
+          
+Clients cannot open new connections to a :binary:`~bin.mongod` or
+:binary:`~bin.mongos` that is shutting down.

source/reference/command/shutdown.txt

@@ -10,13 +10,15 @@ shutdown
    :depth: 1
    :class: singlecol
 
+.. versionchanged:: 5.0
+
 .. dbcommand:: shutdown
 
    The :dbcommand:`shutdown` command cleans up all database resources
    and then terminates the process.  You must issue
    the :dbcommand:`shutdown` command against the :term:`admin database`.
 
-   The command has the following syntax:
+   The command has this syntax:
 
    .. code-block:: javascript
 
@@ -27,7 +29,7 @@ shutdown
         comment: <any>
       })
 
-   The command takes the following optional field:
+   The command takes these fields:
 
    .. list-table::
       :header-rows: 1
@@ -47,19 +49,29 @@ shutdown
         - .. _shutdown-cmd-force:
 
           Optional. Specify ``true`` to force the :binary:`~bin.mongod`
-          to shut down. Force shutdown interrupts any ongoing operations
-          on the :binary:`~bin.mongod` and may result in unexpected
+          or :binary:`~bin.mongos` to shut down. Force shutdown
+          interrupts any ongoing operations on the :binary:`~bin.mongod`
+          or :binary:`~bin.mongos` and may result in unexpected
           behavior.
 
       * - :ref:`timeoutSecs <shutdown-cmd-timeoutSecs>`
 
         - .. _shutdown-cmd-timeoutSecs:
 
-          Optional. The number of seconds the :term:`primary` should 
-          wait for a secondary to catch up. Defaults to ``10``.
+          Optional.
+          
+          .. _shutdown-cmd-quiesce-period:
+
+          .. |force| replace:: :ref:`force <shutdown-cmd-force>`
+          .. |timeout| replace:: :ref:`timeoutSecs <shutdown-cmd-timeoutSecs>`
 
-          If no secondaries catch up within the specified time, the 
-          command fails. 
+          .. include:: /includes/quiesce-period.rst
+
+          In MongoDB 4.4 and earlier, for a :binary:`~bin.mongod`
+          :term:`primary`, :ref:`timeoutSecs <shutdown-cmd-timeoutSecs>`
+          is the number of seconds the :term:`primary` should wait for a
+          secondary to catch up. If no secondaries catch up within the
+          specified time, the command fails. Defaults to ``10`` seconds.
 
       * - ``comment``
 
@@ -93,17 +105,19 @@ certain operations such as :ref:`index builds
 :ref:`force: true <shutdown-cmd-force>` to force the member 
 to interrupt those operations and shut down.
 
-Shutting Down the Replica Set Primary
-`````````````````````````````````````
+Shutting Down the Replica Set Primary, Secondary, or ``mongos``
+```````````````````````````````````````````````````````````````
+
+.. include:: /includes/quiesce-period.rst
 
-If running :dbcommand:`shutdown` against the replica set
-:term:`primary`, the operation implicitly uses
+In MongoDB 4.4 and earlier, if running :dbcommand:`shutdown` against the
+replica set :term:`primary`, the operation implicitly uses
 :dbcommand:`replSetStepDown` to step down the primary before shutting
 down the :binary:`~bin.mongod`. If no secondary in the replica set can
 catch up to the primary within ``10`` seconds, the shutdown operation
-fails. You can issue :dbcommand:`shutdown` with 
-:ref:`force: true <shutdown-cmd-force>` to shut down the primary 
-*even if* the step down fails. 
+fails. You can issue :dbcommand:`shutdown` with :ref:`force: true
+<shutdown-cmd-force>` to shut down the primary *even if* the step down
+fails. 
 
 .. warning::
 

source/reference/method/db.shutdownServer.txt

@@ -10,14 +10,16 @@ db.shutdownServer()
    :depth: 1
    :class: singlecol
 
+.. versionchanged:: 5.0
+
 .. method:: db.shutdownServer()
 
    Shuts down the current :binary:`~bin.mongod` or :binary:`~bin.mongos`
    process cleanly and safely. You must issue the
    :method:`db.shutdownServer()` operation against the 
    :term:`admin database`.
 
-   :method:`db.shutdownServer()` has the following syntax:
+   :method:`db.shutdownServer()` has this syntax:
 
    .. code-block:: javascript
 
@@ -26,7 +28,7 @@ db.shutdownServer()
         timeoutSecs: <int> 
       })
 
-   The method takes the following optional field:
+   The method takes these fields:
 
    .. list-table::
       :header-rows: 1
@@ -40,19 +42,30 @@ db.shutdownServer()
         - .. _shutdownServer-method-force:
 
           Optional. Specify ``true`` to force the :binary:`~bin.mongod`
-          to shut down. Force shutdown interrupts any ongoing 
-          operations on the :binary:`~bin.mongod` and may result in
-          unexpected behavior.
+          or :binary:`~bin.mongos` to shut down. Force shutdown
+          interrupts any ongoing operations on the :binary:`~bin.mongod`
+          or :binary:`~bin.mongos` and may result in unexpected
+          behavior.
 
       * - :ref:`timeoutSecs <shutdownServer-method-timeoutSecs>`
 
         - .. _shutdownServer-method-timeoutSecs:
 
-          Optional. The number of seconds the :term:`primary` should 
-          wait for a secondary to catch up. Defaults to ``10``.
+          Optional.
+
+          .. _shutdownServer-method-quiesce-period:
+
+          .. |force| replace:: :ref:`force <shutdownServer-method-force>`
+          .. |timeout| replace:: :ref:`timeoutSecs <shutdownServer-method-timeoutSecs>`
 
-          If no secondaries catch up within the specified time, the 
-          command fails. 
+          .. include:: /includes/quiesce-period.rst
+
+          In MongoDB 4.4 and earlier, for a :binary:`~bin.mongod`
+          :term:`primary`, :ref:`timeoutSecs
+          <shutdownServer-method-timeoutSecs>` is the number of seconds
+          the :term:`primary` should wait for a secondary to catch up.
+          If no secondaries catch up within the specified time, the
+          command fails. Defaults to ``10`` seconds.
 
 This operation provides a wrapper around the :dbcommand:`shutdown`
 command.
@@ -81,23 +94,25 @@ set member is running certain operations such as :ref:`index builds
 <shutdownServer-method-force>` to force the member to interrupt those
 operations and shut down.
 
-Shutting Down the Replica Set Primary
-`````````````````````````````````````
+Shutting Down the Replica Set Primary, Secondary, or ``mongos``
+```````````````````````````````````````````````````````````````
+
+.. include:: /includes/quiesce-period.rst
 
-If running :method:`db.shutdownServer()` against the replica set
-:term:`primary`, the operation implicitly uses
+In MongoDB 4.4 and earlier, if running :method:`db.shutdownServer()`
+against the replica set :term:`primary`, the operation implicitly uses
 :dbcommand:`replSetStepDown` to step down the primary before shutting
 down the :binary:`~bin.mongod`. If no secondary in the replica set can
 catch up to the primary within ``10`` seconds, the shutdown operation
-fails. You can issue :method:`~db.shutdownServer()` with 
-:ref:`force: true <shutdownServer-method-force>` to shut down the 
-primary *even if* the step down fails.
+fails. You can issue :method:`db.shutdownServer()` with :ref:`force:
+true <shutdownServer-method-force>` to shut down the primary *even if*
+the step down fails.
 
 .. warning::
 
    Force shutdown of the primary can result in the 
    :ref:`rollback <replica-set-rollback>` of any writes not 
-   yet replicated to a secondary. 
+   yet replicated to a secondary.
 
 .. _method-shutdown-access-control:
 

source/reference/parameters.txt

@@ -2733,6 +2733,35 @@ Sharding Parameters
 
       - :parameter:`maxTimeMSForHedgedReads`
 
+.. parameter:: shutdownTimeoutMillisForSignaledShutdown
+
+   .. versionadded:: 5.0
+
+   *Type*: integer
+
+   *Default*: 15000
+
+   |mongod-only|
+   
+   Specifies the time (in milliseconds) to wait for any ongoing database
+   operations to complete before initiating a shutdown of
+   :binary:`~bin.mongod` in response to a ``SIGTERM`` signal.
+
+   For example, to set the time to 250 milliseconds, you can issue the
+   following during startup:
+   
+   .. code-block:: sh
+
+      mongod --setParameter shutdownTimeoutMillisForSignaledShutdown=250
+
+   Or if using the :dbcommand:`setParameter` command in a
+   :binary:`~bin.mongo` shell connected to a running
+   :binary:`~bin.mongod`:
+
+   .. code-block:: javascript
+
+      db.adminCommand( { setParameter: 1, shutdownTimeoutMillisForSignaledShutdown: 250 } )
+
 .. parameter:: mongosShutdownTimeoutMillisForSignaledShutdown
 
    .. versionadded:: 5.0
@@ -2745,7 +2774,7 @@ Sharding Parameters
 
    Specifies the time (in milliseconds) to wait for any ongoing database
    operations to complete before initiating a shutdown of
-   :binary:`~bin.mongos`.
+   :binary:`~bin.mongos` in response to a ``SIGTERM`` signal.
 
    For example, to set the time to 250 milliseconds, you can issue the
    following during startup:

source/release-notes/5.0.txt

@@ -124,6 +124,13 @@ Removed Commands
 Replica Sets
 ------------
 
+Quiesce Period
+~~~~~~~~~~~~~~
+
+Starting in MongoDB 5.0, :binary:`~bin.mongod` and :binary:`~bin.mongos`
+enter a :ref:`quiesce period <shutdown-cmd-quiesce-period>` to allow any
+ongoing database operations to complete before shutting down.
+
 Limit Removed for ``members[n]._id`` Values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~