rs.reconfig()

Definition

  • rs.reconfig(configuration, force)
  • Reconfigures an existing replica set, overwriting the existingreplica set configuration. To run the method, you must connect tothe primary of the replica set.

ParameterTypeDescriptionconfigurationdocumentA document that specifiesthe configuration of a replica set.forcedocumentOptional. If set as { force: true }, this forces the replica set toaccept the new configuration even if a majority of the members arenot accessible. Use with caution, as this can lead torollback situations.

To reconfigure an existing replica set, first retrieve thecurrent configuration with rs.conf(), modify theconfiguration document as needed, and then pass the modifieddocument to rs.reconfig().

rs.reconfig() provides a wrapper around thereplSetReconfig command.

The force parameter allows a reconfiguration command to be issuedto a non-primary node.

Consideration

Access Control

To run the method 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

rs.reconfig() obtains a special mutuallyexclusive lock to prevent more than oners.reconfig() 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

The rs.reconfig() shell method can trigger the current primaryto step down in some situations. Primary step-down triggers anelection to select a new primary:

  • Starting in MongoDB 4.2, when the primary steps down, it no longercloses all client connections and writes that were in progress arekilled. 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

Using rs.reconfig() with { force: true } can lead torollback of majority-committed writes. Exercise caution whenusing this option.

Member Priority and Votes

Changed in version 3.2.

Drop Outgoing Connections After Removing a Member

Using rs.reconfig() to remove a replica set member does notautomatically drop open outgoing connections from other replica setmembers 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:

  1. db.adminCommand(
  2.   {
  3.     "dropConnections" : 1,
  4.     "hostAndPort" : [
  5.       "<hostname>:<port>"
  6.     ]
  7.   }
  8. )

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

Examples

A replica set named rs0 has the following configuration:

  1. {
  2.    "_id" : "rs0",
  3.    "version" : 1,
  4.    "protocolVersion" : NumberLong(1),
  5.    "members" : [
  6.       {
  7.          "_id" : 0,
  8.          "host" : "mongodb0.example.net:27017",
  9.          "arbiterOnly" : false,
  10.          "buildIndexes" : true,
  11.          "hidden" : false,
  12.          "priority" : 1,
  13.          "tags" : {
  14.  
  15.          },
  16.          "slaveDelay" : NumberLong(0),
  17.          "votes" : 1
  18.       },
  19.       {
  20.          "_id" : 1,
  21.          "host" : "mongodb1.example.net:27017",
  22.          "arbiterOnly" : false,
  23.          "buildIndexes" : true,
  24.          "hidden" : false,
  25.          "priority" : 1,
  26.          "tags" : {
  27.  
  28.          },
  29.          "slaveDelay" : NumberLong(0),
  30.          "votes" : 1
  31.       },
  32.       {
  33.          "_id" : 2,
  34.          "host" : "mongodb2.example.net:27017",
  35.          "arbiterOnly" : false,
  36.          "buildIndexes" : true,
  37.          "hidden" : false,
  38.          "priority" : 1,
  39.          "tags" : {
  40.  
  41.          },
  42.          "slaveDelay" : NumberLong(0),
  43.          "votes" : 1
  44.       }
  45.    ],
  46.    "settings" : {
  47.       "chainingAllowed" : true,
  48.       "heartbeatIntervalMillis" : 2000,
  49.       "heartbeatTimeoutSecs" : 10,
  50.       "electionTimeoutMillis" : 10000,
  51.       "catchUpTimeoutMillis" : 2000,
  52.       "getLastErrorModes" : {
  53.  
  54.       },
  55.       "getLastErrorDefaults" : {
  56.          "w" : 1,
  57.          "wtimeout" : 0
  58.       },
  59.       "replicaSetId" : ObjectId("58858acc1f5609ed986b641b")
  60.    }
  61. }

The following sequence of operations updates themembers[n].priority of the second member.The operations are issued through a mongo shell connected tothe primary.

  1. cfg = rs.conf();
  2. cfg.members[1].priority = 2;
  3. rs.reconfig(cfg);

To access the member configuration document in the array, thestatement uses the array index and not the replica set member’smembers[n]._id field.

  • The last statement calls the rs.reconfig() method with themodified cfg to initialize this new configuration. Uponsuccessful reconfiguration, the replica set configuration willresemble the following:
  1. {
  2.    "_id" : "rs0",
  3.    "version" : 2,
  4.    "protocolVersion" : NumberLong(1),
  5.    "members" : [
  6.       {
  7.          "_id" : 0,
  8.          "host" : "mongodb0.example.net:27017",
  9.          "arbiterOnly" : false,
  10.          "buildIndexes" : true,
  11.          "hidden" : false,
  12.          "priority" : 1,
  13.          "tags" : {
  14.  
  15.          },
  16.          "slaveDelay" : NumberLong(0),
  17.          "votes" : 1
  18.       },
  19.       {
  20.          "_id" : 1,
  21.          "host" : "mongodb1.example.net:27017",
  22.          "arbiterOnly" : false,
  23.          "buildIndexes" : true,
  24.          "hidden" : false,
  25.          "priority" : 2,
  26.          "tags" : {
  27.  
  28.          },
  29.          "slaveDelay" : NumberLong(0),
  30.          "votes" : 1
  31.       },
  32.       {
  33.          "_id" : 2,
  34.          "host" : "mongodb2.example.net:27017",
  35.          "arbiterOnly" : false,
  36.          "buildIndexes" : true,
  37.          "hidden" : false,
  38.          "priority" : 1,
  39.          "tags" : {
  40.  
  41.          },
  42.          "slaveDelay" : NumberLong(0),
  43.          "votes" : 1
  44.       }
  45.    ],
  46.    "settings" : {
  47.       "chainingAllowed" : true,
  48.       "heartbeatIntervalMillis" : 2000,
  49.       "heartbeatTimeoutSecs" : 10,
  50.       "electionTimeoutMillis" : 10000,
  51.       "catchUpTimeoutMillis" : 2000,
  52.       "getLastErrorModes" : {
  53.  
  54.       },
  55.       "getLastErrorDefaults" : {
  56.          "w" : 1,
  57.          "wtimeout" : 0
  58.       },
  59.       "replicaSetId" : ObjectId("58858acc1f5609ed986b641b")
  60.    }
  61. }

See also