- Reference >
mongo
Shell Methods >- Replication Methods >
- rs.add()
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 thehost
field in the member configuration document.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. Iftrue
, the added host is an arbiter.rs.add()
provides a wrapper around some of the functionality of thereplSetReconfig
database command and the correspondingmongo
shell helperrs.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
Host name
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:
Add the member initially as a non-voting, priority 0 member:
Ensure that the new member has reached
SECONDARY
state. To check the state of the replica set members, runrs.status()
:Reconfigure the replica set to update the votes and priority of the new member:
where
n
is the array index of the new member in themembers
array.
Warning
- The
rs.reconfig()
shell method can force the current primary to step down, which causes an election. When the primary steps down, themongod
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:
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
Host name
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.