rs.stepDown()¶

On this page

Description¶

rs.stepDown(stepDownSecs, secondaryCatchUpPeriodSecs)¶

Triggers the primary of the replica set to become a secondary. This in turn triggers an 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.

The method only steps down the primary if an electable 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.

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

Parameter Type Description

stepDownSecs

number

The number of seconds to step down the primary, during which time the stepdown member is ineligible for becoming primary. If you specify a non-numeric value, the command uses 60 seconds.

The stepdown period starts from the time that the mongod receives the command. The stepdown period must be greater than the secondaryCatchUpPeriodSecs.

secondaryCatchUpPeriodSecs

number

Optional. The number of seconds that mongod will wait for an electable secondary to catch up to the primary.

When specified, secondaryCatchUpPeriodSecs overrides the default wait time of 10 seconds.

rs.stepDown() provides a wrapper around the command replSetStepDown.

Behavior¶

New in version 3.0.

Before stepping down, 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, 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, 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.

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

rs.stepDown() blocks all writes to the primary while it runs.

← rs.status() rs.syncFrom() →