Navigation
This version of the documentation is archived and no longer supported.

rs.add()

On this page

Definition

rs.add(host, arbiterOnly)

Adds a member to a replica set. To run the method, you must connect to the primary of the replica set.

Parameter Type Description
host string or document

The new member to add to the replica set. Specify either as a string or a configuration document:

  • If a document, specify a replica set member configuration document as found in the members array. You must specify the host field in the member configuration document.

     {
       _id: <int>,
       host: <string>,        // required
       arbiterOnly: <boolean>,
       buildIndexes: <boolean>,
       hidden: <boolean>,
       priority: <number>,
       tags: <document>,
       slaveDelay: <int>,
       votes: <number>
    }
    

    For a description of the configuration field, refer to members.

  • If a string, specify the hostname and optionally the port number for the new member.

arbiterOnly boolean Optional. Applies only if the <host> value is a string. If true, the added host is an arbiter.

rs.add() provides a wrapper around some of the functionality of the replSetReconfig database command and the corresponding mongo shell helper rs.reconfig(). See the Replica Set Configuration document for full documentation of all replica set configuration options.

Behavior

rs.add() can, in some cases, trigger an election for primary which will disconnect the shell (such as adding a new member with a higher priority than the current primary). In such cases, the mongo shell may display an error even if the operation succeeds.

Tip

When a newly added secondary has its votes and priority settings greater than zero, during its initial sync, the secondary still counts as a voting member even though it cannot serve reads nor become primary because its data is not yet consistent.

This can lead to a case where a majority of the voting members are online but no primary can be elected. To avoid such situations, consider adding the new secondary initially with priority :0 and votes :0. Then, once the member has transitioned into SECONDARY state, use rs.reconfig() to update its priority and votes.

Example

Add a Secondary to a New Replica Set

To add a new secondary member with default vote and priority settings to a new replica set, you can call the rs.add() method with:

  • Member Configuration Document

    rs.add( { host: "mongodbd4.example.net:27017" } )
    
  • Host name

    rs.add( "mongodbd4.example.net:27017" )
    

Add a Secondary to an Existing Replica Set

Tip

When a newly added secondary has its votes and priority settings greater than zero, during its initial sync, the secondary still counts as a voting member even though it cannot serve reads nor become primary because its data is not yet consistent.

This can lead to a case where a majority of the voting members are online but no primary can be elected. To avoid such situations, consider adding the new secondary initially with priority :0 and votes :0. Then, once the member has transitioned into SECONDARY state, use rs.reconfig() to update its priority and votes.

To add a new secondary member with default vote and priority settings to an existing replica set:

  1. Add the member initially as a non-voting, priority 0 member:

    rs.add( { host: "mongodbd4.example.net:27017", priority: 0, votes: 0 } )
    
  2. Ensure that the new member has reached SECONDARY state. To check the state of the replica set members, run rs.status():

    rs.status()
    
  3. Reconfigure the replica set to update the votes and priority of the new member:

    var cfg = rs.conf();
    
    cfg.members[n].priority = 1;  // Substitute the correct array index for the new member
    cfg.members[n].votes = 1;     // Substitute the correct array index for the new member
    
    rs.reconfig(cfg)
    

    where n is the array index of the new member in the members array.

Warning

  • The rs.reconfig() shell method can force the current primary to step down, which causes an election. When the primary steps down, the mongod closes all client connections. While this typically takes 10-20 seconds, try to make these changes during scheduled maintenance periods.
  • Avoid reconfiguring replica sets that contain members of different MongoDB versions as validation rules may differ across MongoDB versions.

Add a Priority 0 Member to a Replica Set

The following operation adds a mongod instance, running on the host mongodb4.example.net and accessible on the default port 27017, as a priority 0 secondary member:

rs.add( { host: "mongodbd4.example.net:27017", priority: 0 } )

You must specify the members[n].host field in the member configuration document.

See the members for the available replica set member configuration settings.

Add an Arbiter to a Replica Set

The following operation adds a mongod instance, running on the host mongodb3.example.net and accessible on the default port 27017 as an arbiter:

  • Member Configuration Document

    rs.add( { host: "mongodb3.example.net:27017", arbiterOnly: true } )
    
  • Host name

    rs.add("mongodb3.example.net:27017", true)
    

For the following MongoDB versions, pv1 increases the likelihood of w:1 rollbacks compared to pv0 for replica sets with arbiters:

  • MongoDB 3.4.1
  • MongoDB 3.4.0
  • MongoDB 3.2.11 or earlier

See Replica Set Protocol Versions.

See Replica Set Tutorials for more examples and information.