rs.add()

Definition

  • rs.add(host, arbiterOnly)
  • Adds a member to a replica set. To run the method, you mustconnect to the primary of the replica set.

ParameterTypeDescriptionhoststring or documentThe new member to add to the replica set. Specify either as a stringor a configuration document:

  • If a document, specify a replica set member configuration documentas found in the members array. You must specify thehost field in the member configurationdocument.
  1.  {
  2.    _id: <int>,
  3.    host: <string>,        // required
  4.    arbiterOnly: <boolean>,
  5.    buildIndexes: <boolean>,
  6.    hidden: <boolean>,
  7.    priority: <number>,
  8.    tags: <document>,
  9.    slaveDelay: <int>,
  10.    votes: <number>
  11. }

For a description of the configuration field, refer tomembers.

  • If a string, specify the hostname and optionally the port numberfor the new member.arbiterOnlybooleanOptional. Applies only if the <host> value is a string. If true, theadded host is an arbiter.

rs.add() provides a wrapper around some of thefunctionality of the replSetReconfigdatabasecommand and the corresponding mongo shell helperrs.reconfig(). See theReplica Set Configuration document for fulldocumentation of all replica set configuration options.

IP Binding

Starting in MongoDB 3.6, MongoDB binaries, mongod andmongos, bind to localhost by default. If thenet.ipv6 configuration file setting or the —ipv6command line option is set for the binary, the binary additionally bindsto the localhost IPv6 address.

Previously, starting from MongoDB 2.6, only the binaries from theofficial MongoDB RPM (Red Hat, CentOS, Fedora Linux, and derivatives)and DEB (Debian, Ubuntu, and derivatives) packages bind to localhost bydefault.

When bound only to the localhost, these MongoDB 3.6 binaries can onlyaccept connections from clients (including the mongo shell,other members in your deployment for replica sets and sharded clusters)that are running on the same machine. Remote clients cannot connect tothe binaries bound only to localhost.

To override and bind to other ip addresses, you can use thenet.bindIp configuration file setting or the—bind_ip command-line option to specify a list of hostnames or ipaddresses.

Warning

Before binding to a non-localhost (e.g. publicly accessible)IP address, ensure you have secured your cluster from unauthorizedaccess. For a complete list of security recommendations, seeSecurity Checklist. At minimum, considerenabling authentication andhardening network infrastructure.

For example, the following mongod instance binds to boththe localhost and the hostname My-Example-Associated-Hostname, which isassociated with the ip address 198.51.100.1:

  1. mongod --bind_ip localhost,My-Example-Associated-Hostname

In order to connect to this instance, remote clients must specifythe hostname or its associated ip address 198.51.100.1:

  1. mongo --host My-Example-Associated-Hostname
  2.  
  3. mongo --host 198.51.100.1

Tip

When possible, use a logical DNS hostname instead of an ip address,particularly when configuring replica set members or sharded clustermembers. The use of logical DNS hostnames avoids configurationchanges due to ip address changes.

Behavior

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

Tip

When a newly added secondary has its votes andpriority settings greater than zero, duringits initial sync, the secondary still counts as a voting member eventhough it cannot serve reads nor become primary because its data isnot yet consistent.

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

Example

Add a Secondary to a New Replica Set

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

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

Add a Secondary to an Existing Replica Set

Tip

When a newly added secondary has its votes andpriority settings greater than zero, duringits initial sync, the secondary still counts as a voting member eventhough it cannot serve reads nor become primary because its data isnot yet consistent.

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

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

  1. rs.add( { host: "mongodbd4.example.net:27017", priority: 0, votes: 0 } )
  • Ensure that the new member has reached SECONDARY state.To check the state of the replica set members, runrs.status():
  1. rs.status()
  • Reconfigure the replica set to update the votes and priority of thenew member:
  1. var cfg = rs.conf();
  2.  
  3. cfg.members[n].priority = 1;  // Substitute the correct array index for the new member
  4. cfg.members[n].votes = 1;     // Substitute the correct array index for the new member
  5.  
  6. rs.reconfig(cfg)

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

Warning

  • The rs.reconfig() shell method can force the currentprimary to step down, which causes an election. When the primary steps down, themongod closes all client connections. While thistypically takes 10-20 seconds, try to make these changes duringscheduled maintenance periods.
  • Avoid reconfiguring replica sets that contain members of differentMongoDB 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 onthe host mongodb4.example.net and accessible on the default port27017, as a priority 0secondary member:

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

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

See the members for the available replica set memberconfiguration settings.

Add an Arbiter to a Replica Set

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

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

For the following MongoDB versions, pv1 increases the likelihoodof w:1 rollbacks compared to pv0(no longer supported in MongoDB 4.0+) for replica sets with arbiters:

  • MongoDB 3.4.1
  • MongoDB 3.4.0
  • MongoDB 3.2.11 or earlier

See Replica Set Protocol Version.

See also: