rs.reconfig()
On this page
Definition
rs.reconfig( configuration, force )-
Reconfigures an existing replica set, overwriting the existing replica set configuration. To run the method, you must connect to the primary of the replica set.
Parameter Type Description configurationdocument A document that specifies the configuration of a replica set. forcedocument Optional. If set as { force: true }, this forces the replica set to accept the new configuration even if a majority of the members are not accessible. Use with caution, as this can lead to rollback situations.To reconfigure an existing replica set, first retrieve the current configuration with
rs.conf(), modify the configuration document as needed, and then pass the modified document tors.reconfig().rs.reconfig()provides a wrapper around thereplSetReconfigcommand.The
forceparameter allows a reconfiguration command to be issued to a non-primary node.
Consideration
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
The rs.reconfig() shell method 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
Using rs.reconfig() with { force: true } can lead to rollback of committed writes. Exercise caution when using this option.
protocolVersion
Before changing the protocolVersion, ensure that at least one oplog entry (generated from the current protocol version) has replicated from the primary to all secondaries. For details, see Modify Replica Set Protocol Version.
Examples
A replica set named rs0 has the following configuration:
{
"_id" : "rs0",
"version" : 1,
"protocolVersion" : NumberLong(1),
"members" : [
{
"_id" : 0,
"host" : "mongodb0.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
},
{
"_id" : 1,
"host" : "mongodb1.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
},
{
"_id" : 2,
"host" : "mongodb2.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
}
],
"settings" : {
"chainingAllowed" : true,
"heartbeatIntervalMillis" : 2000,
"heartbeatTimeoutSecs" : 10,
"electionTimeoutMillis" : 10000,
"catchUpTimeoutMillis" : 2000,
"getLastErrorModes" : {
},
"getLastErrorDefaults" : {
"w" : 1,
"wtimeout" : 0
},
"replicaSetId" : ObjectId("58858acc1f5609ed986b641b")
}
}
The following sequence of operations updates the members[n].priority of the second member. The operations are issued through a mongo shell connected to the primary.
cfg = rs.conf();
cfg.members[1].priority = 2;
rs.reconfig(cfg);
The first statement uses the
rs.conf()method to retrieve a document containing the current configuration for the replica set and sets the document to the local variablecfg.The second statement sets a
members[n].priorityvalue to the second document in themembersarray. For additional settings, see replica set configuration settings.To access the member configuration document in the array, the statement uses the array index and not the replica set member’s
members[n]._idfield.The last statement calls the
rs.reconfig()method with the modifiedcfgto initialize this new configuration. Upon successful reconfiguration, the replica set configuration will resemble the following:
{
"_id" : "rs0",
"version" : 2,
"protocolVersion" : NumberLong(1),
"members" : [
{
"_id" : 0,
"host" : "mongodb0.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
},
{
"_id" : 1,
"host" : "mongodb1.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 2,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
},
{
"_id" : 2,
"host" : "mongodb2.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
}
],
"settings" : {
"chainingAllowed" : true,
"heartbeatIntervalMillis" : 2000,
"heartbeatTimeoutSecs" : 10,
"electionTimeoutMillis" : 10000,
"catchUpTimeoutMillis" : 2000,
"getLastErrorModes" : {
},
"getLastErrorDefaults" : {
"w" : 1,
"wtimeout" : 0
},
"replicaSetId" : ObjectId("58858acc1f5609ed986b641b")
}
}