replSetStepDown¶

On this page

Description
Behavior
Examples

Description¶

replSetStepDown¶

Forces the primary of the replica set to become a secondary, triggering an 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 electable 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. replSetStepDown can only run in the admin database and has the following prototype form:

db.runCommand( {
    replSetStepDown: <seconds>,
    secondaryCatchUpPeriodSecs: <seconds>,
    force: <true|false>
} )

replSetStepDown takes the following fields as arguments:

Field Type Description

replSetStepDown

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 the mongod will wait for an electable secondary to catch up to the primary.

When specified, secondaryCatchUpPeriodSecs overrides the default wait time of either 10 seconds or if force: true, 0 seconds.

force

boolean

Optional. A boolean that determines whether the primary steps down if no electable and up-to-date secondary exists within the wait period.

If true, the primary steps down even if no suitable secondary member exists; this could lead to rollbacks if a secondary with replication lag becomes the new primary.

If false, the primary does not step down if no suitable secondary member exists and the command returns an error.

Defaults to false.

Behavior¶

New in version 3.0.

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

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.

Upon successful stepdown, 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.

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

replSetStepDown blocks all writes to the primary while it runs.

Examples¶

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 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.

use admin
db.runCommand( { replSetStepDown: 120 } )

Specify Wait Time for Secondary Catch Up¶

The following example, run on the current primary, attempts to step 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.

use admin
db.runCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15 } )

Specify Secondary Catch Up with Force Step Down¶

The following example, run on the current primary, attempts to step 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.

use admin
db.runCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15, force: true } )