replSetStepDown
Description
replSetStepDown
- Instructs the primary of the replica set to become asecondary. After the primary steps down, eligble secondaries willhold an election for primary.
The command does not immediately step down the primary. If noelectable
secondariesare up to date with the primary, the primary waits up tosecondaryCatchUpPeriodSecs
(by default 10 seconds) for asecondary to catch up. Once an electable secondary isavailable, the command steps down the primary.
Once stepped down, the original primary becomes a secondary and isineligible from becoming primary again for the remainder of timespecified by replSetStepDown: <seconds>
.
For a detailed explanation of the command ‘s execution,see Behavior.
Note
The command is only valid against the primary and throws anerror if run on a non-primary member.
The replSetStepDown
can only run on the admin
databaseand has the following prototype form:
- db.adminCommand( {
- replSetStepDown: <seconds>,
- secondaryCatchUpPeriodSecs: <seconds>,
- force: <true|false>
- } )
replSetStepDown
takes the following fields as arguments:
FieldTypeDescriptionreplSetStepDown
numberThe number of seconds to step down the primary, during which time thestepdown member is ineligible for becoming primary. If you specify anon-numeric value, the command uses 60
seconds.
The stepdown period starts from the time that themongod
receives the command. The stepdown period mustbe greater than the secondaryCatchUpPeriodSecs
.secondaryCatchUpPeriodSecs
numberOptional. The number of seconds that the mongod
will wait foran electable secondary to catch up to the primary.
When specified, secondaryCatchUpPeriodSecs
overrides the defaultwait time of either 10
seconds or if force: true
, 0
seconds.force
booleanOptional. A boolean that determines whether the primary steps down if no electableand up-to-date secondary exists within the wait period.
If true
, the primary steps down even if no suitable secondarymember exists; this could lead to rollbacks if a secondary with replication lagbecomes the new primary.
If false
, the primary does not step down if no suitable secondarymember exists and the command returns an error.
Defaults to false
.
Behavior
Concurrent Operations
The replSetStepDown
command attempts toterminate long running user operations that block the primaryfrom stepping down, such as an index build, a write operation or amap-reduce job.
Availability of Eligible Secondaries
The command then initiates a catchup period where it waits up tosecondaryCatchUpPeriodSeconds
, by default 10 seconds, for asecondary to become up-to-date with the primary. The primary only stepsdown if a secondary is up-to-date with the primary during thecatchup period to prevent rollbacks.
If no electable secondary meets this criterion by the end of the waitingperiod, the primary does not step down and the command errors.You can override this behavior and issue with command with the force: true
option to immediately step down the primary.
Once the primary steps down successfully, that node cannot become theprimary for the remainder of the replSetStepDown: <seconds>
period,which began when the node received the command.
Client Connections
Starting in MongoDB 4.2, replSetStepDown
command nolonger closes all client connections.
In MongoDB 4.0 and earlier, replSetStepDown
commandcloses all client connections during the step down. Because thedisconnect includes the connection used to run the command,you cannot retrieve the return status of the command if thecommand completes successfully. You can only retrieve thereturn status of the command if it errors. When running the4.0 and earlier command in a script, the script shouldaccount for this behavior.
Writes During Stepdown
Note
All writes to the primary fail during the period starting when thereplSetStepDown
command is received until either a newprimary is elected, or if there are no electable secondaries, theoriginal primary resumes normal operation.
Writes that were in progress when replSetStepDown
is runare killed. In-progress transactionsalso fail with "TransientTransactionError" and can beretried as a whole.
The time period where writes fail is at maximum:
secondaryCatchUpPeriodSecs
(10s by default) +electionTimeoutMillis
(10s by default).
Election Handoff
Changed in version 4.0.2: If the parameter enableElectionHandoff
is true(default), when a primary steps down from rs.stepDown()
(or the replSetStepDown
command without the force:true
), the stepped-down primary nominates an eligible secondaryto call an election immediately. Otherwise, secondaries can waitup to settings.electionTimeoutMillis
before calling anelection. The stepped down primary does not wait for the effectsof the handoff. For more information, seeenableElectionHandoff
.
Examples
Step Down with Default Options
The following example, run on the current primary, attempts to stepdown the member for 120
seconds.
The operation waits up to the default 10
seconds for asecondary to catch up. If no suitable secondary exists, the primarydoes not step down and the command errors.
Note
All writes to the primary fail during the period starting when thereplSetStepDown
command is received until either a newprimary is elected, or if there are no electable secondaries, theoriginal primary resumes normal operation.
Writes that were in progress when replSetStepDown
is runare killed. In-progress transactionsalso fail with "TransientTransactionError" and can beretried as a whole.
The time period where writes fail is at maximum:
secondaryCatchUpPeriodSecs
(10s by default) +electionTimeoutMillis
(10s by default).
- db.adminCommand( { replSetStepDown: 120 } )
Specify Wait Time for Secondary Catch Up
The following example, run on the current primary, attempts to stepdown the member for 120
seconds, waiting up to 15
seconds foran electable secondary to catch up. If no suitable secondary exists,the primary does not step down and the command errors.
Note
All writes to the primary fail during the period starting when thereplSetStepDown
command is received until either a newprimary is elected, or if there are no electable secondaries, theoriginal primary resumes normal operation.
Writes that were in progress when replSetStepDown
is runare killed. In-progress transactionsalso fail with "TransientTransactionError" and can beretried as a whole.
The time period where writes fail is at maximum:
secondaryCatchUpPeriodSecs
(10s by default) +electionTimeoutMillis
(10s by default).
- db.adminCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15 } )
Specify Secondary Catch Up with Force Step Down
The following example, run on the current primary, attempts to stepdown the member for 120
seconds, waiting up to 15
seconds foran electable secondary to catch up. Because of the force: true
option, the primary steps down even if no suitable secondary exists.
Note
All writes to the primary fail during the period starting when thereplSetStepDown
command is received until either a newprimary is elected, or if there are no electable secondaries, theoriginal primary resumes normal operation.
Writes that were in progress when replSetStepDown
is runare killed. In-progress transactionsalso fail with "TransientTransactionError" and can beretried as a whole.
The time period where writes fail is at maximum:
secondaryCatchUpPeriodSecs
(10s by default) +electionTimeoutMillis
(10s by default).
- db.adminCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15, force: true } )
See also