Navigation
This is an upcoming (i.e. in progress) version of the manual.

replSetReconfig

replSetReconfig

The replSetReconfig administrative command modifies the configuration of an existing replica set. You can use this command to add and remove members, and to alter the options set on existing members. You must run this command on the admin database of the primary replica set member.

The command has the following syntax:

db.adminCommand({
  replSetReconfig: <new_config_document>,
  force: false
})

The command takes the following optional field:

Field Description
force

Defaults to false. Specify true to force the available replica set members to accept the new configuration.

Use this option if there is no current primary in the replica set, or to restore a replica set to new servers with different hostnames.

You may also run replSetReconfig with the shell’s rs.reconfig() method.

Considerations

Locking Behavior

replSetReconfig obtains a special mutually exclusive lock to prevent more than one replSetReconfig operation from occurring at the same time.

Mixed Version Replica Set

Warning

Avoid reconfiguring replica sets that contain members of different MongoDB versions as validation rules may differ across MongoDB versions.

Availability

A majority of the set’s members must be operational for the changes to propagate properly.

replSetReconfig can trigger the current primary to step down in some situations. When the primary steps down, it forcibly closes all client connections. Primary step-down triggers an election to select a new primary.

The median time before a cluster elects a new primary should not typically exceed 12 seconds, assuming default replica configuration settings. This includes time required to mark the primary as unavailable and call and complete an election. You can tune this time period by modifying the settings.electionTimeoutMillis replication configuration option. Factors such as network latency may extend the time required for replica set elections to complete, which in turn affects the amount of time your cluster may operate without a primary. These factors are dependent on your particular cluster architecture.

During the election process, the cluster cannot accept write operations until it elects the new primary.

Your application connection logic should include tolerance for automatic failovers and the subsequent elections.

New in version 3.6: MongoDB 3.6+ drivers can detect the loss of the primary and automatically retry certain write operations a single time, providing additional built-in handling of automatic failovers and elections.

To further reduce potential impact to a production cluster, reconfigure only during scheduled maintenance periods.

{ force: true }

Warning

Forcing the replSetReconfig command can lead to a rollback situation. Use with caution.

Drop Outgoing Connections After Removing a Member

Using replSetReconfig to remove a replica set member does not automatically drop open outgoing connections from other replica set members to the removed member.

By default, replica set members wait for 5 minutes before dropping connections to the removed member. In sharded replica sets, you can modify this timeout using the ShardingTaskExecutorPoolHostTimeoutMS server parameter.

New in version 4.2: To immediately drop all outgoing connections from the replica set to the removed member, run the dropConnections administrative command on each remaining member on the replica set:

db.adminCommand(
  {
    "dropConnections" : 1,
    "hostAndPort" : [
      "<hostname>:<port>"
    ]
  }
)

Replace <hostname> and <port> with those of the removed member.

Member Priority and Votes

Changed in version 3.2.