Navigation

rs.add()

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.

If a string, specify the hostname and optionally the port number for the new member. See Pass a Hostname String to rs.add() for an example.

If a document, specify a replica set member configuration document as found in the members array. You must specify members[n]._id and the members[n].host fields in the member configuration document. See Pass a Member Configuration Document to rs.add() for an example.

See Replica Set Configuration document for full documentation of all replica set configuration options

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.

IP Binding

Starting in MongoDB 3.6, MongoDB binaries, mongod and mongos, bind to localhost (127.0.0.1) 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 IPv6 address ::1.

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 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 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 ip addresses.

Warning

Before you bind to other ip addresses, consider enabling access control and other security measures listed in Security Checklist to prevent unauthorized access.

For example, the following mongod instance binds to both the localhost and the sample ip address 198.51.100.1:

mongod --bind_ip localhost,198.51.100.1

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

mongo --host 198.51.100.1

mongo --host My-Example-Associated-Hostname

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.

Example

Pass a Hostname String to rs.add()

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

rs.add('mongodb3.example.net:27017')

If mongodb3.example.net is an arbiter, use the following form:

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.

Pass a Member Configuration Document to rs.add()

Changed in version 3.0.0: Previous versions required an _id field in the document you passed to rs.add(). After 3.0.0 you can omit the _id field in this document. members[n]._id describes the requirements for specifying _id.

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 Replica Set Configuration for the available replica set member configuration settings.

See also: