diff --git a/source/includes/fact-stepdown-write-fail.rst b/source/includes/fact-stepdown-write-fail.rst new file mode 100644 index 00000000000..1d8b10a5f79 --- /dev/null +++ b/source/includes/fact-stepdown-write-fail.rst @@ -0,0 +1,10 @@ +.. note:: + + All writes to the primary fail during the period starting when the + |command-method-name| |command-method| is received until either a new + primary is elected, or if there are no electible secondaries, the + original primary resumes normal operation. The time period where + writes fail is at maximum: + + ``secondaryCatchUpPeriodSecs`` (10s by default) + + :rsconf:`~settings.electionTimeoutMillis` (10s by default). diff --git a/source/includes/stepdown-behavior.rst b/source/includes/stepdown-behavior.rst new file mode 100644 index 00000000000..db12581782e --- /dev/null +++ b/source/includes/stepdown-behavior.rst @@ -0,0 +1,30 @@ +.. versionadded:: 3.0 + +The |command-method-name| |command-method| attempts to +terminate long running user operations that block the primary +from stepping down, such as an index build, a write operation or a +map-reduce job. + +The |command-method| then initiates a catchup period where it waits up to +``secondaryCatchUpPeriodSeconds``, by default 10 seconds, for a +secondary to become up-to-date with the primary. The primary only steps +down if a secondary is up-to-date with the primary during the +catchup period to prevent :doc:`rollbacks `. + +If no electable secondary meets this criterion by the end of the waiting +period, the primary does not step down and the |command-method| errors. +|force-option| + +Once the primary steps down successfully, that node cannot become the +primary for the remainder of the |stepdown-secs| period, +which began when the node received the |command-method|. The +|command-method-name| |command-method| forces all clients currently +connected to the database to disconnect. This helps ensure that the +clients maintain an accurate view of the replica set. + +Because the disconnect includes the connection used to run the +|command-method|, you cannot retrieve the return status of the +|command-method| if the |command-method| completes successfully. You can +only retrieve the return status of the |command-method| if it errors. +When running the |command-method| in a script, the script should account +for this behavior. diff --git a/source/includes/stepdown-intro.rst b/source/includes/stepdown-intro.rst new file mode 100644 index 00000000000..13939569da3 --- /dev/null +++ b/source/includes/stepdown-intro.rst @@ -0,0 +1,22 @@ +Instructs the :term:`primary` of the replica set to become a +:term:`secondary`. After the primary steps down, eligble secondaries will +hold an :ref:`election for primary `. + +The |command-method| does not immediately step down the primary. If no +:data:`electable <~replSetGetConfig.members[n].priority>` secondaries +are up to date with the primary, the primary waits up to +``secondaryCatchUpPeriodSecs`` (by default 10 seconds) for a +secondary to catch up. Once an electable secondary is +available, the |command-method| steps down the primary. + +Once stepped down, the original primary becomes a secondary and is +ineligible from becoming primary again for the remainder of time +specified by |stepdown-secs|. + +For a detailed explanation of the |command-method| 's execution, +see |behavior-ref|. + +.. note:: + + The |command-method| is only valid against the primary and throws an + error if run on a non-primary member. diff --git a/source/reference/command/replSetStepDown.txt b/source/reference/command/replSetStepDown.txt index 22a8669cc9c..f7d4a26f68b 100644 --- a/source/reference/command/replSetStepDown.txt +++ b/source/reference/command/replSetStepDown.txt @@ -15,25 +15,18 @@ Description .. dbcommand:: replSetStepDown - Forces the :term:`primary` of the replica set to become a - :term:`secondary`, triggering an :ref:`election for primary - `. The command steps down the - primary for a specified number of seconds; during this period, the - stepdown member is ineligible from becoming primary. - - By default, the command only steps down the primary if an - :data:`electable <~replSetGetConfig.members[n].priority>` - secondary is up-to-date with the primary, waiting up to 10 seconds - for a secondary to catch up. - - The command is only valid against the primary and will error if run - on a non-primary member. :dbcommand:`replSetStepDown` can - only run in the ``admin`` database and has the following prototype - form: + .. |command-method| replace:: command + .. |stepdown-secs| replace:: ``replSetStepDown: `` + .. |behavior-ref| replace:: :ref:`replSetStepDown-behavior` + + .. include:: /includes/stepdown-intro.rst + + The :dbcommand:`replSetStepDown` can only run on the ``admin`` database + and has the following prototype form: .. code-block:: javascript - db.runCommand( { + db.adminCommand( { replSetStepDown: , secondaryCatchUpPeriodSecs: , force: @@ -43,39 +36,18 @@ Description .. include:: /includes/apiargs/command-replSetStepDown-field.rst +.. _replSetStepDown-behavior: + Behavior -------- -.. versionadded:: 3.0 - -Before stepping down, :dbcommand:`replSetStepDown` will attempt to -terminate long running user operations that would block the primary -from stepping down, such as an index build, a write operation or a -map-reduce job. - -To avoid rollbacks, :dbcommand:`replSetStepDown`, by default, only -steps down the primary if an electable secondary is completely caught up -with the primary. The command will wait up to the -``secondaryCatchUpPeriodSecs`` for a secondary to catch up. +.. |force-option| replace:: You can override this behavior and issue with command with the ``force: true`` option to immediately step down the primary. -If no electable secondary meets this criterion by the waiting period, -the primary does not step down and the command errors. However, you can -override this behavior by including the ``force: true`` option. +.. |command-method-name| replace:: :dbcommand:`replSetStepDown` -Upon successful stepdown, :dbcommand:`replSetStepDown` forces all -clients currently connected to the database to disconnect. This helps -ensure that the clients maintain an accurate view of the replica set. +.. include:: /includes/stepdown-behavior.rst -Because the disconnect includes the connection used to run the command, -you cannot retrieve the return status of the command if the command -completes successfully; i.e. you can only retrieve the return status of -the command if it errors. When running the command in a script, the -script should account for this behavior. - -.. note:: - - :dbcommand:`replSetStepDown` blocks all writes to the primary while - it runs. +.. include:: /includes/fact-stepdown-write-fail.rst Examples -------- @@ -86,14 +58,13 @@ Step Down with Default Options The following example, run on the current primary, attempts to step down the member for ``120`` seconds. -The operation will wait up to the default ``10`` seconds for a +The operation waits up to the default ``10`` seconds for a secondary to catch up. If no suitable secondary exists, the primary does not step down and the command errors. -.. note:: - - The command blocks all writes to the primary while it runs. +.. include:: /includes/fact-stepdown-write-fail.rst +.. class:: copyable-code .. code-block:: javascript db.adminCommand( { replSetStepDown: 120 } ) @@ -106,10 +77,9 @@ down the member for ``120`` seconds, waiting up to ``15`` seconds for an electable secondary to catch up. If no suitable secondary exists, the primary does not step down and the command errors. -.. note:: - - The command blocks all writes to the primary while it runs. +.. include:: /includes/fact-stepdown-write-fail.rst +.. class:: copyable-code .. code-block:: javascript db.adminCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15 } ) @@ -122,10 +92,9 @@ down the member for ``120`` seconds, waiting up to ``15`` seconds for an electable secondary to catch up. Because of the ``force: true`` option, the primary steps down even if no suitable secondary exists. -.. note:: - - The command blocks all writes to the primary while it runs. +.. include:: /includes/fact-stepdown-write-fail.rst +.. class:: copyable-code .. code-block:: javascript db.adminCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15, force: true } ) diff --git a/source/reference/method/rs.stepDown.txt b/source/reference/method/rs.stepDown.txt index a57a55bfbf3..1cc2642d058 100644 --- a/source/reference/method/rs.stepDown.txt +++ b/source/reference/method/rs.stepDown.txt @@ -15,19 +15,11 @@ Description .. method:: rs.stepDown(stepDownSecs, secondaryCatchUpPeriodSecs) - Triggers the :term:`primary` of the replica set to become a - :term:`secondary`. This in turn triggers an :ref:`election for primary - `. The method steps down the primary - for a specified number of seconds; during this period, the stepdown - member is ineligible from becoming primary. + .. |command-method| replace:: method + .. |stepdown-secs| replace:: ``stepDownSecs`` + .. |behavior-ref| replace:: :ref:`rs.stepDown-behavior` - The method only steps down the primary if an :data:`electable - <~replSetGetConfig.members[n].priority>` secondary is up-to-date - with the primary, waiting up to 10 seconds, by default, for a secondary to catch - up. - - The method is only valid against the primary and will error if run - on a non-primary member. + .. include:: /includes/stepdown-intro.rst The :method:`rs.stepDown()` method has the following parameters: @@ -36,35 +28,15 @@ Description :method:`rs.stepDown()` provides a wrapper around the command :dbcommand:`replSetStepDown`. +.. _rs.stepDown-behavior: + Behavior -------- -.. versionadded:: 3.0 - -Before stepping down, :method:`rs.stepDown()` will attempt to -terminate long running user operations that would block the primary -from stepping down, such as an index build, a write operation or a -map-reduce job. - -To avoid rollbacks, :method:`rs.stepDown()`, by default, only -steps down the primary if an electable secondary is completely caught up -with the primary. The command will wait up to either 10 seconds or the -``secondaryCatchUpPeriodSecs`` for a secondary to catch up. - -If no electable secondary meets this criterion by the waiting period, -the primary does not step down and the method throws an exception. - -Upon successful stepdown, :method:`rs.stepDown()` forces all -clients currently connected to the database to disconnect. This helps -ensure that the clients maintain an accurate view of the replica set. +.. |force-option| replace:: \ -Because the disconnect includes the connection used to run the command, -you cannot retrieve the return status of the command if the command -completes successfully; i.e. you can only retrieve the return status of -the command if it errors. When running the command in a script, the -script should account for this behavior. +.. |command-method-name| replace:: :method:`rs.stepDown()` -.. note:: +.. include:: /includes/stepdown-behavior.rst - :method:`rs.stepDown()` blocks all writes to the primary while it - runs. +.. include:: /includes/fact-stepdown-write-fail.rst