rs.stepDown()

Description

• rs.stepDown(stepDownSecs, secondaryCatchUpPeriodSecs)
• Instructs the primary of the replica set to become asecondary. After the primary steps down, eligble secondaries willhold an election for primary.

The method 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 method 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 stepDownSecs.

For a detailed explanation of the method ‘s execution,see Behavior.

Note

The method is only valid against the primary and throws anerror if run on a non-primary member.

The rs.stepDown() method has the following parameters:

ParameterTypeDescriptionstepDownSecsnumberThe 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.secondaryCatchUpPeriodSecsnumberOptional. The number of seconds that mongod will wait for anelectable secondary to catch up to the primary.

When specified, secondaryCatchUpPeriodSecsoverrides the default wait time of 10 seconds.

rs.stepDown() provides a wrapper around thecommand replSetStepDown.

Behavior

Concurrent Operations

The rs.stepDown() method 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 method 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 method errors.

Once the primary steps down successfully, that node cannot become theprimary for the remainder of the stepDownSecs period,which began when the node received the method.

Client Connections

Starting in MongoDB 4.2, rs.stepDown() method nolonger closes all client connections.

In MongoDB 4.0 and earlier, rs.stepDown() methodcloses all client connections during the step down. Because thedisconnect includes the connection used to run the method,you cannot retrieve the return status of the method if themethod completes successfully. You can only retrieve thereturn status of the method if it errors. When running the4.0 and earlier method in a script, the script shouldaccount for this behavior.

Writes During Stepdown

Note

All writes to the primary fail during the period starting when thers.stepDown() method 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 rs.stepDown() 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.