Replica Set Commands

Shell Helpers

rs.help()                       show help
rs.status()                     { replSetGetStatus : 1 }
rs.initiate()                   { replSetInitiate : null } initiate
                                    with default settings
rs.initiate(cfg)                { replSetInitiate : cfg }
rs.add(hostportstr)             add a new member to the set
rs.add(membercfgobj)            add a new member to the set
rs.addArb(hostportstr)          add a new member which is arbiterOnly:true
rs.remove(hostportstr)          remove a member (primary, secondary, or arbiter) from the set
rs.stepDown()                   { replSetStepDown : true }
rs.conf()                       return configuration from local.system.replset
db.isMaster()                   check who is primary

rs.conf() can be particularly useful when using commands that manipulate a replica set, such as replSetReconfig, because it can be used to get a copy of the current configuration which can be modified and then put back. For an example of this, see Reconfiguring when Members are Up.

Commands

isMaster

Checks if the node to which we are connecting is currently primary. Most drivers do this check automatically and then send queries to the current primary.

Returns an object that looks like:

> db.adminCommand( { isMaster : 1 } )
{
    "setName" : "florble",
    "ismaster" : false,
    "secondary" : true,
    "hosts" : [
        "sf1.example.com",
        "sf4.example.com",
        "ny3.example.com"
    ],
    "passives" : [
        "sf3.example.com",
        "sf2.example.com",
        "ny2.example.com",
    ],
    "arbiters" : [
        "ny1.example.com",
    ]
    "primary" : "sf4.example.com",
    "me" : "ny3.example.com",
    "maxBsonObjectSize" : 16777216,
    "ok" : 1
}

The hosts array lists primary and secondary servers, the passives array lists passive servers, and the arbiters array lists arbiters.

If the "ismaster" field is false, there will be a "primary" field that indicates which server is primary.

replSetGetStatus

Get status on the replica set from this node's point of view. rs.status() is the mongo shell helper for this command. The output looks like:

> db.adminCommand( { replSetGetStatus : 1 } )
{
        "set" : "foo",
        "date" : ISODate("2012-01-06T00:30:47Z"),
        "myState" : 1,
        "members" : [
                {
                        "_id" : 0,
                        "name" : "localhost:27018",
                        "health" : 1,
                        "state" : 1,
                        "stateStr" : "PRIMARY",
                        "optime" : {
                                "t" : 1325809572000,
                                "i" : 1
                        },
                        "optimeDate" : ISODate("2012-01-06T00:26:12Z"),
                        "self" : true
                },
                {
                        "_id" : 1,
                        "name" : "localhost:27019",
                        "health" : 1,
                        "state" : 2,
                        "stateStr" : "SECONDARY",
                        "uptime" : 274,
                        "optime" : {
                                "t" : 1325809572000,
                                "i" : 1
                        },
                        "optimeDate" : ISODate("2012-01-06T00:26:12Z"),
                        "lastHeartbeat" : ISODate("2012-01-06T00:30:47Z"),
                        "pingMs" : 0
                },
                {
                        "_id" : 2,
                        "name" : "localhost:27020",
                        "health" : 1,
                        "state" : 2,
                        "stateStr" : "SECONDARY",
                        "uptime" : 274,
                        "optime" : {
                                "t" : 1325809572000,
                                "i" : 1
                        },
                        "optimeDate" : ISODate("2012-01-06T00:26:12Z"),
                        "lastHeartbeat" : ISODate("2012-01-06T00:30:47Z"),
                        "pingMs" : 1
                }
        ],
        "ok" : 1
}

state

The state, myState, and stateStr fields indicates the state of this server. Possible state values are:

health

The health field indicates the health of the server/member. Typical values are zero if a server is down (from this server's POV) and 1 if it is up.

pingMs

The pingMs field (v2.0+) reports how long heartbeat commands take from this member to the other member. When members are performing well the pingMs value should approach the round trip ping times of the network between the nodes. If a server is overloaded, this value could be significant larger (which would indicate a problem). Also if the network has problems this value will intermittently report a high value. The metric is an ongoing average of the last several ping requests (represenative of average ping time for roughly say, the last minute).

optime, optimeDate

The optime, optimeDate fields specify the timestamp of the last operation on the node. This value could be a bit behind realtime as heartbeat requests between servers only occur every few seconds. Thus the real replication lag might be very low even if this statistic shows a few seconds.

errmsg

The errmsg field contains informational messages, as shown above.

replSetInitiate

> db.adminCommand( { replSetInitiate : <config> } )

Initiate a replica set. Run this command at one node only, to initiate the set. Whatever data is on the initiating node becomes the initial data for the set. This is a one time operation done at cluster creation. rs.initiate(<cfg>) is the mongo shell helper for this command. See also Configuration.

replSetReconfig

Adjust configuration of a replica set (just like initialize).

db._adminCommand({replSetReconfig: cfg })

Note: db._adminCommand is short-hand for db.getSisterDB("admin").runCommand();

Note: as of v1.7.2, replSetReconfig closes all connections, meaning there will be no database response to this command.

force option

As of 2.0 you can force a reconfigure when you have less than a majority of the replica set up using the {force:true} option.

replSetStepDown

 db.adminCommand( { replSetStepDown : <seconds> } )

Manually tell a member to step down as primary. Node will become eligible to be primary again after the specified number of seconds. (Presumably, another node will take over by then if it were eligible.)

If the primary cannot see anyone who has synced to within 10 seconds of its latest op, the primary will reject the step down request. You can force the request by passing a force : true option.

For example:

> db.adminCommand({replSetStepDown : 1})
{
        "closest" : 1302040824,
        "difference" : 25,
        "errmsg" : "no secondaries within 10 seconds of my optime",
        "ok" : 0
}
> db.adminCommand({replSetStepDown : 1, force : true})
// works

v1.7.2+: replSetStepDown closes all connections, meaning there will be no database response to this command.

v1.7.3+: the seconds parameter above can be specified. In older versions, the step down was always for one minute only.

v1.9.0+: Added ability for primary to reject step down and added force option.

replSetFreeze

 db.adminCommand( { replSetFreeze : <seconds> } )

v1.7.3+

'Freeze' state of this member to the extent we can do that. What this really means is that this node will not attempt to become primary until the time period specified expires.

You can call again with {replSetFreeze:0} to unfreeze sooner. A process restart unfreezes the member also.

If the node is already primary, you need to use replSetStepdown instead.