Connecting Drivers to Replica Sets
This legacy documentation does not necessarily reflect the current practices in MongoDB driver implementation, but may be useful for historical purposes. See the MongoDB Meta Driver for the current documentation of MongoDB driver implementation.
Ideally a MongoDB driver can connect to a cluster of servers which represent a replica set, and automatically find the right set member with which to communicate. Failover should be automatic too. The general steps are:
- The user, when opening the connection, specifies host[:port] for one or more members of the set. Not all members need be specified. In fact the exact members of the set might change over time. This list for the connect call is the seed list.
- The driver then connects to all servers on the seed list, perhaps in parallel to minimize connect time. Send an isMaster command to each server.
- When the server is in replSet mode, it will return a hosts field with all members of the set that are potentially eligible to serve data. The client should cache this information. Ideally this refreshes too, as the set’s config could change over time.
- Choose a server with which to communicate.
- If ismaster == true, that server is primary for the set. This server can be used for writes and immediately consistent reads.
- If secondary == true, that server is not primary, but is available for eventually consistent reads. In this case, you can use the primary field to see which server the master should be. (If primary is not set, you may want to poll other nodes at random; it is conceivable that the member to which we are talking is partitioned from the other members, and thus it cannot determine who is primary on its own. This is unlikely but possible.)
- If an error occurs with the current connection, find the new primary and resume use there.
For example, if we run the ismaster command on a non-primary server, we might get something like:
"ismaster" : false,
"secondary" : true,
"hosts" : [
"passives" : [
"arbiters" : [
"primary" : "ny2.acme.com",
"ok" : true
There are three servers with priority > 0 (ny1, ny2, and sf1), two passive servers (ny3 and sf3), and an arbiter (sf2). The primary should be ny2, but the driver should call isMaster on that server before it assumes it is.