- Replication >
- Replica Set Commands
Replica Set Commands¶
On this page
This reference collects documentation for all JavaScript methods for the mongo
shell that
support replica set functionality, as well as all
database commands related to
replication function.
See Replication, for a list of all replica set documentation.
JavaScript Methods¶
The following methods apply to replica sets. For a complete list of all methods, see JavaScript Methods.
-
rs.
status
()¶ Returns: A document with status information. This output reflects the current status of the replica set, using data derived from the heartbeat packets sent by the other members of the replica set.
This method provides a wrapper around the
replSetGetStatus
database command.See also
“Replica Set Status Reference” for documentation of this output.
-
db.
isMaster
()¶ Returns a status document with fields that includes the
ismaster
field that reports if the current node is the primary node, as well as a report of a subset of current replica set configuration.This function provides a wrapper around the database command
isMaster
-
rs.
initiate
(configuration)¶ Parameters: - configuration – Optional. A document that specifies the configuration of a replica set. If not specified, MongoDB will use a default configuration.
Initiates a replica set. Optionally takes a configuration argument in the form of a document that holds the configuration of a replica set. Consider the following model of the most basic configuration for a 3-member replica set:
This function provides a wrapper around the “
replSetInitiate
” database command.
-
rs.
conf
()¶ Returns: a document that contains the current replica set configuration object.
-
rs.
config
()¶ rs.config()
is an alias ofrs.conf()
.
-
rs.
reconfig
(configuration[, force])¶ Parameters: - configuration – A document that specifies the configuration of a replica set.
- force – Optional. Specify
{ force: true }
as the force parameter to force the replica set to accept the new configuration even if a majority of the members are not accessible. Use with caution, as this can lead to rollback situations.
Initializes a new replica set configuration. This function will disconnect the shell briefly and forces a reconnection as the replica set renegotiates which node will be primary. As a result, the shell will display an error even if this command succeeds.
rs.reconfig()
provides a wrapper around the “replSetReconfig
” database command.rs.reconfig()
overwrites the existing replica set configuration. Retrieve the current configuration object withrs.conf()
, modify the configuration as needed and then users.reconfig()
to submit the modified configuration object.To reconfigure a replica set, use the following sequence of operations:
If you want to force the reconfiguration if a majority of the set isn’t connected to the current member, or you’re issuing the command against a secondary, use the following form:
Warning
Forcing a
rs.reconfig()
can lead to rollback situations and other difficult to recover from situations. Exercise caution when using this option.See also
“Replica Set Configuration” and “Replica Set Operation and Management”.
-
rs.
add
(hostspec, arbiterOnly)¶ Specify one of the following forms:
Parameters: - host (string,document) – Either a string or a document. If a string, specifies a host (and optionally port-number) for a new host member for the replica set; MongoDB will add this host with the default configuration. If a document, specifies any attributes about a member of a replica set.
- arbiterOnly (boolean) – Optional. If
true
, this host is an arbiter. If the second argument evaluates totrue
, as is the case with some documents, then this instance will become an arbiter.
Provides a simple method to add a member to an existing replica set. You can specify new hosts in one of two ways:
- as a “hostname” with an optional port number to use the default configuration as in the Add a Member to an Existing Replica Set example.
- as a configuration document, as in the Add a Member to an Existing Replica Set (Alternate Procedure) example.
This function will disconnect the shell briefly and forces a reconnection as the replica set renegotiates which node will be primary. As a result, the shell will display an error even if this command succeeds.
rs.add()
provides a wrapper around some of the functionality of the “replSetReconfig
” database command and the corresponding shell helperrs.reconfig()
. See the Replica Set Configuration document for full documentation of all replica set configuration options.Example
To add a
mongod
accessible on the default port27017
running on the hostmongodb3.example.net
, use the followingrs.add()
invocation:If
mongodb3.example.net
is an arbiter, use the following form:To add
mongodb3.example.net
as a secondary-only member of set, use the following form ofrs.add()
:Replace,
3
with the next unused_id
value in the replica set. Seers.conf()
to see the existing_id
values in the replica set configuration document.See the Replica Set Configuration and Replica Set Operation and Management documents for more information.
-
rs.
addArb
(hostname)¶ Parameters: - host (string) – Specifies a host (and optionally port-number) for an arbiter member for the replica set.
Adds a new arbiter to an existing replica set.
This function will disconnect the shell briefly and forces a reconnection as the replica set renegotiates which node will be primary. As a result, the shell will display an error even if this command succeeds.
-
rs.
stepDown
(seconds)¶ Parameters: - seconds (init) – Specify the duration of this operation. If not specified the command uses the default value of 60 seconds.
Returns: disconnects shell.
Forces the current replica set member to step down as primary and then attempt to avoid election as primary for the designated number of seconds. Produces an error if the current node is not primary.
This function will disconnect the shell briefly and forces a reconnection as the replica set renegotiates which node will be primary. As a result, the shell will display an error even if this command succeeds.
rs.stepDown()
provides a wrapper around the database commandreplSetStepDown
.
-
rs.
freeze
(seconds)¶ Parameters: - seconds (init) – Specify the duration of this operation.
Forces the current node to become ineligible to become primary for the period specified.
rs.freeze()
provides a wrapper around the database commandreplSetFreeze
.
-
rs.
remove
(hostname)¶ Parameters: - hostname – Specify one of the existing hosts to remove from the current replica set.
Removes the node described by the
hostname
parameter from the current replica set. This function will disconnect the shell briefly and forces a reconnection as the replica set renegotiates which node will be primary. As a result, the shell will display an error even if this command succeeds.Note
Before running the
rs.remove()
operation, you must shut down the replica set member that you’re removing.Changed in version 2.2: This procedure is no longer required when using
rs.remove()
, but it remains good practice.
-
db.
isMaster
()¶ Returns a status document with fields that includes the
ismaster
field that reports if the current node is the primary node, as well as a report of a subset of current replica set configuration.This function provides a wrapper around the database command
isMaster
-
rs.
help
()¶ Returns a basic help text for all of the replication related shell functions.
-
rs.
syncFrom
()¶ New in version 2.2.
Provides a wrapper around the
replSetSyncFrom
, which allows administrators to configure the member of a replica set that the current member will pull data from. Specify the name of the member you want to replicate from in the form of[hostname]:[port]
.See
replSetSyncFrom
for more details.
Database Commands¶
The following commands apply to replica sets. For a complete list of all commands, see Database Commands Quick Reference.
-
isMaster
¶ The
isMaster
command provides a basic overview of the current replication configuration. MongoDB drivers and clients use this command to determine what kind of member they’re connected to and to discover additional members of a replica set. Thedb.isMaster()
method provides a wrapper around this database command.The command takes the following form:
This command returns a document containing the following fields:
-
isMaster.
setname
¶ The name of the current replica set, if applicable.
-
isMaster.
ismaster
¶ A boolean value that reports when this node is writable. If
true
, then the current node is either a primary in a replica set, a master in a master-slave configuration, or a standalonemongod
.
-
isMaster.
secondary
¶ A boolean value that, when
true
, indicates that the current member is a secondary member of a replica set.
-
isMaster.
hosts
¶ An array of strings in the format of “
[hostname]:[port]
” listing all members of the replica set that are not “hidden”.
-
isMaster.
arbiter
¶ An array of strings in the format of “
[hostname]:[port]
” listing all members of the replica set that are arbitersOnly appears in the
isMaster
response for replica sets that have arbiter members.
-
isMaster.
arbiterOnly
¶ A boolean value that, when
true
indicates that the current instance is an arbiter.arbiterOnly
only appears in theisMaster
response from arbiters.
-
isMaster.
primary
¶ The
[hostname]:[port]
for the current replica set primary, if applicable.
-
isMaster.
me
¶ The
[hostname]:[port]
of the node responding to this command.
-
-
resync
¶ The
resync
command forces an out-of-date slavemongod
instance to re-synchronize itself. Note that this command is relevant to master-slave replication only. It does not apply to replica sets.Warning
This command obtains a global write lock and will block other operations until it has completed.
-
replSetFreeze
¶ The
replSetFreeze
command prevents a replica set member from seeking election for the specified number of seconds. Use this command in conjunction with thereplSetStepDown
command to make a different node in the replica set a primary.The
replSetFreeze
command uses the following syntax:If you want to unfreeze a replica set member before the specified number of seconds has elapsed, you can issue the command with a seconds value of
0
:Restarting the
mongod
process also unfreezes a replica set member.replSetFreeze
is an administrative command, and you must issue the it against the admin database.
-
replSetGetStatus
¶ The
replSetGetStatus
command returns the status of the replica set from the point of view of the current server. You must run the command against the admin database. The command has the following prototype format:However, you can also run this command from the shell like so:
See also
“Replica Set Status Reference” and “Replica Set Fundamental Concepts”
-
replSetInitiate
¶ The
replSetInitiate
command initializes a new replica set. Use the following syntax:The
<config_document>
is a document that specifies the replica set’s configuration. For instance, here’s a config document for creating a simple 3-member replica set:A typical way of running this command is to assign the config document to a variable and then to pass the document to the
rs.initiate()
helper:See also
“Replica Set Configuration,” “Replica Set Operation and Management,” and “Replica Set Reconfiguration.”
-
replSetMaintenance
¶ The
replSetMaintenance
admin command enables or disables the maintenance mode for a secondary member of a replica set.The command has the following prototype form:
Consider the following behavior when running the
replSetMaintenance
command:- You cannot run the command on the Primary.
- You must run the command against the
admin
database. - When enabled
replSetMaintenance: 1
, the member enters theRECOVERING
state. While the secondary isRECOVERING
:- The member is not accessible for read operations.
- The member continues to sync its oplog from the Primary.
-
replSetReconfig
¶ The
replSetReconfig
command modifies the configuration of an existing replica set. You can use this command to add and remove members, and to alter the options set on existing members. Use the following syntax:You may also run the command using the shell’s
rs.reconfig()
method.Be aware of the following
replSetReconfig
behaviors:You must issue this command against the admin database of the current primary member of the replica set.
You can optionally force the replica set to accept the new configuration by specifying
force: true
. Use this option if the current member is not primary or if a majority of the members of the set are not accessible.Warning
Forcing the
replSetReconfig
command can lead to a rollback situation. Use with caution.Use the force option to restore a replica set to new servers with different hostnames. This works even if the set members already have a copy of the data.
A majority of the set’s members must be operational for the changes to propagate properly.
This command can cause downtime as the set renegotiates primary-status. Typically this is 10-20 seconds, but could be as long as a minute or more. Therefore, you should attempt to reconfigure only during scheduled maintenance periods.
In some cases,
replSetReconfig
forces the current primary to step down, initiating an election for primary among the members of the replica set. When this happens, the set will drop all current connections.
Note
replSetReconfig
obtains a special mutually exclusive lock to prevent more than onereplSetReconfig
operation from occurring at the same time.
-
replSetSyncFrom
¶ New in version 2.2.
Options: - host – Specifies the name and port number of the replica set member
that this member replicates from. Use
the
[hostname]:[port]
form.
replSetSyncFrom
allows you to explicitly configure which host the currentmongod
will poll oplog entries from. This operation may be useful for testing different patterns and in situations where a set member is not replicating from the host you want. The member to replicate from must be a valid source for data in the set.A member cannot replicate from:
- itself.
- an arbiter, because arbiters do not hold data.
- a member that does not build indexes.
- an unreachable member.
- a
mongod
instance that is not a member of the same replica set.
If you attempt to replicate from a member that is more than 10 seconds behind the current member,
mongod
will return and log a warning, but it still will replicate from the member that is behind.If you run
rs.syncFrom()
during initial sync, MongoDB produces no error messages, but the sync target will not change until after the initial sync operation.The command has the following prototype form:
To run the command in the
mongo
shell, use the following invocation:You may also use the
rs.syncFrom()
helper in themongo
shell, in an operation with the following form:Note
replSetSyncFrom
andrs.syncFrom()
provide a temporary override of default behavior. If:- the
mongod
instance restarts or - the connection to the sync target closes;
then, the
mongod
instance will revert to the default sync logic and target.- host – Specifies the name and port number of the replica set member
that this member replicates from. Use
the