- Reference >
- Database Commands >
- Replication Commands >
- replSetReconfig
replSetReconfig¶
On this page
-
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 theadmin
database of the primary replica set member.Tip
In the mongo Shell, this command can also be run through the
rs.reconfig
helper method.Helper methods are convenient for mongo users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.
The command has the following syntax:
The command takes the following optional field:
Field Description force
Defaults to
false
. Specifytrue
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’srs.reconfig()
method.
Considerations¶
Access Control¶
To run the command on deployments that enforce access
control, the user must have
replSetConfigure
privilege action on the cluster
resource. The clusterManager
built-in role, available in
the admin
database, provides the required privileges for this
command.
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. Primary step-down triggers
an election to select a new
primary:
- Starting in MongoDB 4.2, when the primary steps down, it no longer closes all client connections; however, writes that were in progress are killed. For details, see Behavior.
- In MongoDB 4.0 and earlier, when the primary steps down, it closes all client connections.
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. MongoDB 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:
Compatible drivers enable retryable writes by default
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:
Replace <hostname>
and <port>
with those of the removed
member.
Additional Information¶
Replica Set Configuration Fields,
Replica Set Configuration, rs.reconfig()
, and
rs.conf()
.