Database Manual / Reference / Database Commands / Replication

replSetStepDown (database command数据库命令)

Description描述

replSetStepDown

Instructs the primary of the replica set to become a secondary. After the primary steps down, eligible secondaries hold an election for primary.指示副本集的primary成为secondary。初选结束后，符合条件的secondary将选举primary。

The command does not immediately step down the primary. 该命令不会立即关闭主服务器。If no electable secondaries are up to date with the primary, the primary waits up to secondaryCatchUpPeriodSecs (by default 10 seconds) for a secondary to catch up. 如果没有可选择的secondary与primary保持同步，则主服务器最多等待secondaryCatchUpPeriodSecs（次服务器赶上次服务器）（默认情况下为10秒）。Once an electable secondary is available, the command 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 replSetStepDown: <seconds>.一旦降级，原始主服务器将变为次服务器，在replSetStepDown: <seconds>指定的剩余时间内没有资格再次成为主服务器。

For a detailed explanation of the command 's execution, see Behavior.有关命令执行的详细说明，请参阅行为。

Note

The command is only valid against the primary and throws an error if run on a non-primary member.该命令仅对主成员有效，如果在非主成员上运行，则会抛出错误。

Tip

In mongosh, this command can also be run through the rs.stepDown() helper method.在mongosh中，此命令也可以通过rs.stepDown()辅助方法运行。

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. 助手方法对mongosh用户来说很方便，但它们可能不会返回与数据库命令相同级别的信息。In cases where the convenience is not needed or the additional return fields are required, use the database command.如果不需要便利性或需要额外的返回字段，请使用database命令。

The replSetStepDown can only run on the admin database.replSetStepDown只能在admin数据库上运行。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用：

  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Important

This command is not supported in MongoDB Atlas clusters. MongoDB Atlas集群不支持此命令。For information on Atlas support for all commands, see Unsupported Commands.有关Atlas支持所有命令的信息，请参阅不支持的命令。

Syntax语法

The command has the following syntax:该命令具有以下语法：

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

Command Fields命令字段

The command takes the following fields:该命令包含以下字段：

Field字段Type类型Description描述
replSetStepDownnumber数字

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.降级主要成员的秒数，在此期间，降级成员没有资格成为主要成员。如果指定非数字值，则该命令将使用60秒。

The stepdown period starts from the time that the mongod receives the command. The stepdown period must be greater than the secondaryCatchUpPeriodSecs.降级期从mongod收到命令的时间开始。降级周期必须大于secondaryCatchUpPeriodSecs。

secondaryCatchUpPeriodSecsnumber数字

Optional. 可选。The number of seconds that the mongod will wait for an electable secondary to catch up to the primary.mongod等待可选举的secondary赶上primary的秒数。

When specified, secondaryCatchUpPeriodSecs overrides the default wait time of either 10 seconds or if force: true, 0 seconds.指定后，secndaryCatchUpPeriodSecs将覆盖默认的等待时间10秒，或者如果force:true，则覆盖0秒。

forceboolean布尔值

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.如果为true，即使不存在合适的次要成员，主要成员也会降级；如果具有复制延迟的次服务器成为新的主服务器，这可能会导致回滚。

If false, the primary does not step down if no suitable secondary member exists and the command returns an error.如果为false，则如果不存在合适的辅助成员，则主成员不会降级，并且命令返回错误。

Defaults to false.默认为false。

Behavior行为

Concurrent Operations并发操作

The replSetStepDown command 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.replSetStepDown命令尝试终止长时间运行的用户操作，这些操作会阻止主服务器降级，例如索引构建、写入操作或映射缩减作业。

Availability of Eligible Secondaries合格借调人员的可用性

The command 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. 然后，该命令会启动一个追赶期，在此期间，它最多等待secondaryCatchUpPeriodSeconds，默认情况下为10秒，以便次服务器与主服务器保持最新状态。The primary only steps down if a secondary is up-to-date with the primary during the catchup period to prevent rollbacks.只有当辅助服务器在追赶期间与主服务器保持最新状态时，主服务器才会降级，以防止回滚。

If no electable secondary meets this criterion by the end of the waiting period, 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.如果在等待期结束时，没有可选择的次级符合此标准，则初级不会降级，命令也会出错。您可以覆盖此行为，并使用force:true选项发出命令，以立即关闭主界面。

Once the primary steps down successfully, that node cannot become the primary for the remainder of the replSetStepDown: <seconds> period, which began when the node received the command.一旦主节点成功降级，该节点在replSetStepDown: <seconds>时段的剩余时间内无法成为主节点，该时段从节点收到命令时开始。

Client Connections客户端连接

replSetStepDown command doesn't close all client connections.命令不会关闭所有客户端连接。

Writes During Stepdown卸任期间写作

Note

All writes to the primary fail during the period starting when the replSetStepDown command is received until either a new primary is elected, or if there are no electable secondaries, the original primary resumes normal operation.从收到replSetStepDown命令开始，直到选择新的主服务器，或者如果没有可选择的次服务器，则原始主服务器恢复正常运行，在此期间，对主服务器的所有写入都失败。

Writes that were in progress when replSetStepDown is run are killed. 运行replSetStepDown时正在进行的写入操作将被终止。In-progress transactions also fail with TransientTransactionError and can be retried as a whole.正在进行的事务也会因TransientTransactionError而失败，并且可以整体重试。

The time period where writes fail is at maximum:写入失败的时间段最多为：

secondaryCatchUpPeriodSecs (10s by default) + electionTimeoutMillis (10s by default).

Election Handoff选举交接

When you step down a primary using rs.stepDown() or replSetStepDown without setting the force field to true, the stepped-down primary nominates an eligible secondary to call an election immediately.当你在不将force字段设置为true的情况下使用rs.stepDown()或replSetStepDown退出初选时，被降级的初选会提名一个符合条件的次选立即进行选举。

Examples示例

Step Down with Default Options使用默认选项降级

The following example, run on the current primary, attempts to step down the member for 120 seconds.以下示例在当前主服务器上运行，尝试将成员降级120秒。

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.该操作最多等待默认的10秒，以便辅助服务器赶上。如果不存在合适的辅助设备，则主设备不会降级，命令也会出错。

Note

All writes to the primary fail during the period starting when the replSetStepDown command is received until either a new primary is elected, or if there are no electable secondaries, the original primary resumes normal operation.从收到replSetStepDown命令开始，直到选择新的主服务器，或者如果没有可选择的次服务器，则原始主服务器恢复正常运行，在此期间，对主服务器的所有写入都失败。

Writes that were in progress when replSetStepDown is run are killed. 运行replSetStepDown时正在进行的写入操作将被终止。In-progress transactions also fail with TransientTransactionError and can be retried as a whole.正在进行的事务也会因TransientTransactionError而失败，并且可以整体重试。

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 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.以下示例在当前主服务器上运行，尝试将成员降级120秒，最多等待15秒，等待可选择的次服务器赶上。如果不存在合适的辅助设备，则主设备不会降级，命令也会出错。

Note

All writes to the primary fail during the period starting when the replSetStepDown command is received until either a new primary is elected, or if there are no electable secondaries, the original primary resumes normal operation.从收到replSetStepDown命令开始，直到选择新的主服务器，或者如果没有可选择的次服务器，则原始主服务器恢复正常运行，在此期间，对主服务器的所有写入都失败。

Writes that were in progress when replSetStepDown is run are killed. 运行replSetStepDown时正在进行的写入操作将被终止。In-progress transactions also fail with TransientTransactionError and can be retried as a whole.正在进行的事务也会因TransientTransactionError而失败，并且可以整体重试。

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 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.以下示例在当前主服务器上运行，尝试将成员降级120秒，最多等待15秒，等待可选择的次服务器赶上。由于force: true选项，即使没有合适的次要选项，主要选项也会降级。

Note

All writes to the primary fail during the period starting when the replSetStepDown command is received until either a new primary is elected, or if there are no electable secondaries, the original primary resumes normal operation.从收到replSetStepDown命令开始，直到选择新的主服务器，或者如果没有可选择的次服务器，则原始主服务器恢复正常运行，在此期间，对主服务器的所有写入都失败。

Writes that were in progress when replSetStepDown is run are killed. 运行replSetStepDown时正在进行的写入操作将被终止。In-progress transactions also fail with TransientTransactionError and can be retried as a whole.正在进行的事务也会因TransientTransactionError而失败，可以整体重试。

The time period where writes fail is at maximum:写入失败的时间段最多为：

secondaryCatchUpPeriodSecs (10s by default) + electionTimeoutMillis (10s by default).（默认10秒）+electionTimeoutMillis（默认10 s）。

db.adminCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15, force: true } )

Tip

rs.stepDown()