diff --git a/source/includes/quiesce-period.rst b/source/includes/quiesce-period.rst new file mode 100644 index 00000000000..5cffdaa2a7e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/source/reference/command/shutdown.txt b/source/reference/command/shutdown.txt index 1aa6f3ade59..c4c31b1379b 100644 --- a/source/reference/command/shutdown.txt +++ b/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: }) - 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: - 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 ` + .. |timeout| replace:: :ref:`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 ` + 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 ` 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 ` to shut down the primary -*even if* the step down fails. +fails. You can issue :dbcommand:`shutdown` with :ref:`force: true +` to shut down the primary *even if* the step down +fails. .. warning:: diff --git a/source/reference/method/db.shutdownServer.txt b/source/reference/method/db.shutdownServer.txt index 4daba10ec49..64436dbec23 100644 --- a/source/reference/method/db.shutdownServer.txt +++ b/source/reference/method/db.shutdownServer.txt @@ -10,6 +10,8 @@ db.shutdownServer() :depth: 1 :class: singlecol +.. versionchanged:: 5.0 + .. method:: db.shutdownServer() Shuts down the current :binary:`~bin.mongod` or :binary:`~bin.mongos` @@ -17,7 +19,7 @@ db.shutdownServer() :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: }) - 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: - 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 ` + .. |timeout| replace:: :ref:`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 + ` 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 ` 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 ` to shut down the -primary *even if* the step down fails. +fails. You can issue :method:`db.shutdownServer()` with :ref:`force: +true ` to shut down the primary *even if* +the step down fails. .. warning:: Force shutdown of the primary can result in the :ref:`rollback ` of any writes not - yet replicated to a secondary. + yet replicated to a secondary. .. _method-shutdown-access-control: diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index 70900be8ff3..97a820cc7ae 100644 --- a/source/reference/parameters.txt +++ b/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: diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 0ddfcab222d..8867a41e0bf 100644 --- a/source/release-notes/5.0.txt +++ b/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 ` to allow any +ongoing database operations to complete before shutting down. + Limit Removed for ``members[n]._id`` Values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~