Docs Menu

rs.add()

On this page

  • Definition
  • IP Binding
  • Behavior
  • Example
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>,
    secondaryDelaySecs: <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 mongosh helper rs.reconfig(). See the Replica Set Configuration document for full documentation of all replica set configuration options.

Starting in MongoDB 3.6, MongoDB binaries, mongod and mongos, bind to localhost by default. If the net.ipv6 configuration file setting or the --ipv6 command line option is set for the binary, the binary additionally binds to the localhost IPv6 address.

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

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

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

Warning

Before binding to a non-localhost (e.g. publicly accessible) IP address, ensure you have secured your cluster from unauthorized access. For a complete list of security recommendations, see Security Checklist. At minimum, consider enabling authentication and hardening network infrastructure.

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

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

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

mongosh --host My-Example-Associated-Hostname
mongosh --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 cluster members. The use of logical DNS hostnames avoids configuration changes due to ip address changes.

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, mongosh may display an error even if the operation succeeds.

Warning

Before MongoDB 5.0, a newly added secondary still counts as a voting member even though it can neither serve reads nor become primary until its data is consistent. If you are running a MongoDB version earlier than 5.0 and add a secondary with its votes and priority settings greater than zero, 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, run rs.status() to ensure the member has transitioned into SECONDARY state. Finally, use rs.reconfig() to update its priority and votes.

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 new secondary member with default vote and priority settings to an existing replica set:

rs.add( { host: "mongodbd4.example.net:27017" } )
Warning

Before MongoDB 5.0, a newly added secondary still counts as a voting member even though it can neither serve reads nor become primary until its data is consistent. If you are running a MongoDB version earlier than 5.0 and add a secondary with its votes and priority settings greater than zero, 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, run rs.status() to ensure the member has transitioned into SECONDARY state. Finally, use rs.reconfig() to update its priority and votes.

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.

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 (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:

Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.