replSetReconfig

• replSetReconfig
• The replSetReconfig administrative command modifies theconfiguration of an existing replica set. You can use this command toadd and remove members, and to alter the options set on existingmembers. You must run this command on the admindatabase 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:

FieldDescriptionforceDefaults to false. Specify true to force theavailable replica set members to accept the new configuration.

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

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

Considerations

Access Control

To run the command on deployments that enforce accesscontrol, the user must havereplSetConfigure privilege action on the clusterresource. The clusterManager built-in role, available inthe admin database, provides the required privileges for thiscommand.

Locking Behavior

replSetReconfig obtains a special mutuallyexclusive lock to prevent more than onereplSetReconfig operation from occurring at the sametime.

Mixed Version Replica Set

Warning

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

Availability

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

replSetReconfig can trigger the currentprimary to step down in some situations. Primary step-down triggersan election to select a newprimary:

• Starting in MongoDB 4.2, when the primary steps down, it no longercloses all client connections; however, writes that were in progressare killed. For details, see Behavior.
• In MongoDB 4.0 and earlier, when the primary steps down, it closesall client connections.

The median time before a cluster elects a new primary should nottypically exceed 12 seconds, assuming default replicaconfiguration settings. This includes time required tomark the primary as unavailable andcall and complete an election.You can tune this time period by modifying thesettings.electionTimeoutMillis replication configurationoption. Factors such as network latency may extend the time requiredfor replica set elections to complete, which in turn affects the amountof time your cluster may operate without a primary. These factors aredependent on your particular cluster architecture.

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

Your application connection logic should include tolerance for automaticfailovers and the subsequent elections. Starting in MongoDB 3.6, MongoDB driverscan detect the loss of the primary and automaticallyretry certain write operations a single time,providing additional built-in handling of automatic failovers and elections:

• MongoDB 4.2-compatible drivers enable retryable writes by default
• MongoDB 4.0 and 3.6-compatible drivers must explicitly enableretryable writes by including retryWrites=true in the connection string.

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 arollback situation. Use with caution.

Drop Outgoing Connections After Removing a Member

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

By default, replica set members wait for 5 minutes before droppingconnections to the removed member. In sharded replica sets, you canmodify this timeout using theShardingTaskExecutorPoolHostTimeoutMS server parameter.

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

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

Replace <hostname> and <port> with those of the removedmember.

Member Priority and Votes

Changed in version 3.2.

• Members with priority greater than 0 cannot have0 votes.
• Non-voting members must have priority of 0.

Additional Information

Replica Set Configuration Fields,Replica Set Configuration, rs.reconfig(), andrs.conf().