diff --git a/reference/mongo/mongo/gethosts.xml b/reference/mongo/mongo/gethosts.xml new file mode 100644 index 0000000000..343a1e2d60 --- /dev/null +++ b/reference/mongo/mongo/gethosts.xml @@ -0,0 +1,155 @@ + + + + + + Mongo::getHosts + Updates status for all hosts associated with this + + + + &reftitle.description; + + public arrayMongo::getHosts + + + + + This method can only be used with a connection to a replica set. It returns + the status of all of the hosts in the set and updates the connection + information (the updating is invisible to the user). + + + + This is called automatically by the driver every five seconds. + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns an array of information about the hosts in the set. Includes each + host's hostname, id in the set, health (1 is healthy), the uptime, and how + up-to-date the host is compared to the primary. For example, on a + three-member replica set running locally, it might look something like: + + + Array + ( + [_id] => 0 + [name] => ubuntu:27017 + [health] => 1 + [state] => 1 + [stateStr] => PRIMARY + [optime] => MongoTimestamp Object + ( + [sec] => 1 + [inc] => 1291155754 + ) + + [optimeDate] => MongoDate Object + ( + [sec] => 1291155754 + [usec] => 0 + ) + + [self] => 1 + ) + + [ubuntu:27019] => Array + ( + [_id] => 2 + [name] => ubuntu:27019 + [health] => 1 + [state] => 2 + [stateStr] => SECONDARY + [uptime] => 91928 + [optime] => MongoTimestamp Object + ( + [sec] => 1 + [inc] => 1291155754 + ) + + [optimeDate] => MongoDate Object + ( + [sec] => 1291155754 + [usec] => 0 + ) + + [lastHeartbeat] => MongoDate Object + ( + [sec] => 1291158846 + [usec] => 0 + ) + + ) + + [ubuntu:27018] => Array + ( + [_id] => 1 + [name] => ubuntu:27018 + [health] => 1 + [state] => 2 + [stateStr] => SECONDARY + [uptime] => 91944 + [optime] => MongoTimestamp Object + ( + [sec] => 1 + [inc] => 1291155754 + ) + + [optimeDate] => MongoDate Object + ( + [sec] => 1291155754 + [usec] => 0 + ) + + [lastHeartbeat] => MongoDate Object + ( + [sec] => 1291158846 + [usec] => 0 + ) + + ) + +) +]]> + + + This returns &null; if the connection is not connected to a replica set or + has not been initialized, yet. + + + + diff --git a/reference/mongo/mongo/getslave.xml b/reference/mongo/mongo/getslave.xml new file mode 100644 index 0000000000..d2150d9f42 --- /dev/null +++ b/reference/mongo/mongo/getslave.xml @@ -0,0 +1,65 @@ + + + + + + Mongo::getSlave + Returns the address being used by this for slaveOkay reads + + + + &reftitle.description; + + public stringMongo::getSlave + + + + + This finds the address of the slave currently being used for reads. It is a + read-only method: it does not change anything about the internal state of the + object. + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + The address of the slave this connection is using for reads. + + + This returns &null; if this is not connected to a replica set or not yet + initialized. + + + + + diff --git a/reference/mongo/mongo/getslaveokay.xml b/reference/mongo/mongo/getslaveokay.xml new file mode 100644 index 0000000000..623999e0d1 --- /dev/null +++ b/reference/mongo/mongo/getslaveokay.xml @@ -0,0 +1,53 @@ + + + + + + Mongo::getSlaveOkay + Get slaveOkay setting for this connection + + + + &reftitle.description; + + public booleanMongo::getSlaveOkay + + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the value of slaveOkay for this instance. + + + + diff --git a/reference/mongo/mongo/setslaveokay.xml b/reference/mongo/mongo/setslaveokay.xml new file mode 100644 index 0000000000..aaeb2107aa --- /dev/null +++ b/reference/mongo/mongo/setslaveokay.xml @@ -0,0 +1,67 @@ + + + + + + Mongo::setSlaveOkay + Change slaveOkay setting for this connection + + + + &reftitle.description; + + public booleanMongo::setSlaveOkay + booleanok + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + &reftitle.parameters; + + + + + ok + + + + If reads should be sent to secondary members of a replica set for all + possible queries using this Mongo instance. + + + + + + + + + &reftitle.returnvalues; + + Returns the former value of slaveOkay for this instance. + + + + diff --git a/reference/mongo/mongo/switchslave.xml b/reference/mongo/mongo/switchslave.xml new file mode 100644 index 0000000000..2fa805f6e3 --- /dev/null +++ b/reference/mongo/mongo/switchslave.xml @@ -0,0 +1,81 @@ + + + + + + Mongo::switchSlave + Choose a new slave for slaveOkay reads + + + + &reftitle.description; + + public stringMongo::switchSlave + + + + + This choses a random slave for a connection to read from. It is called + automatically by the driver and should not need to be used. It calls + Mongo::getHosts (to refresh the status of hosts) and + Mongo::getSlave (to get the return value). + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + The address of the slave this connection is using for reads. This may be the + same as the previous address as addresses are randomly chosen. It may return + only one address if only one secondary (or only the primary) is available. + + + For example, if we had a three member replica set with a primary, secondary, + and arbiter this method would always return the address of the secondary. + If the secondary became unavailable, this method would always return the + address of the primary. If the primary also became unavailable, this method + would throw an exception, as an arbiter cannot handle reads. + + + + + &reftitle.errors; + + Throws a MongoException (error code 15) if it is + called on a non-replica-set connection. It will also throw + MongoExceptions if it cannot find anyone (primary or + secondary) to read from (error code 16). + + + + + diff --git a/reference/mongo/mongocollection/getslaveokay.xml b/reference/mongo/mongocollection/getslaveokay.xml new file mode 100644 index 0000000000..fef066fb4d --- /dev/null +++ b/reference/mongo/mongocollection/getslaveokay.xml @@ -0,0 +1,53 @@ + + + + + + MongoCollection::getSlaveOkay + Get slaveOkay setting for this collection + + + + &reftitle.description; + + public booleanMongoCollection::getSlaveOkay + + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the value of slaveOkay for this instance. + + + + diff --git a/reference/mongo/mongocollection/setslaveokay.xml b/reference/mongo/mongocollection/setslaveokay.xml new file mode 100644 index 0000000000..554fa33484 --- /dev/null +++ b/reference/mongo/mongocollection/setslaveokay.xml @@ -0,0 +1,68 @@ + + + + + + MongoCollection::setSlaveOkay + Change slaveOkay setting for this collection + + + + &reftitle.description; + + public booleanMongoCollection::setSlaveOkay + booleanok + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + &reftitle.parameters; + + + + + ok + + + + If reads should be sent to secondary members of a replica set for all + possible queries using this MongoCollection + instance. + + + + + + + + + &reftitle.returnvalues; + + Returns the former value of slaveOkay for this instance. + + + + diff --git a/reference/mongo/mongocursor/slaveokay.xml b/reference/mongo/mongocursor/slaveokay.xml index 8a16d5b8c7..d517dd1517 100644 --- a/reference/mongo/mongocursor/slaveokay.xml +++ b/reference/mongo/mongocursor/slaveokay.xml @@ -1,7 +1,7 @@ - + MongoCursor::slaveOkay Sets whether this query can be done on a slave diff --git a/reference/mongo/mongodb/getslaveokay.xml b/reference/mongo/mongodb/getslaveokay.xml new file mode 100644 index 0000000000..4d3778ad6b --- /dev/null +++ b/reference/mongo/mongodb/getslaveokay.xml @@ -0,0 +1,53 @@ + + + + + + MongoDB::getSlaveOkay + Get slaveOkay setting for this database + + + + &reftitle.description; + + public booleanMongoDB::getSlaveOkay + + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the value of slaveOkay for this instance. + + + + diff --git a/reference/mongo/mongodb/setslaveokay.xml b/reference/mongo/mongodb/setslaveokay.xml new file mode 100644 index 0000000000..dbaa772e5f --- /dev/null +++ b/reference/mongo/mongodb/setslaveokay.xml @@ -0,0 +1,67 @@ + + + + + + MongoDB::setSlaveOkay + Change slaveOkay setting for this database + + + + &reftitle.description; + + public booleanMongoDB::setSlaveOkay + booleanok + + + + See the query section of this manual for + information on distributing reads to slaves. + + + + + &reftitle.parameters; + + + + + ok + + + + If reads should be sent to secondary members of a replica set for all + possible queries using this MongoDB instance. + + + + + + + + + &reftitle.returnvalues; + + Returns the former value of slaveOkay for this instance. + + + + diff --git a/reference/mongo/queries.xml b/reference/mongo/queries.xml index 4470e27ad6..055c40967e 100644 --- a/reference/mongo/queries.xml +++ b/reference/mongo/queries.xml @@ -3,6 +3,175 @@
Querying +
+ Distributing queries to slaves + + + 1.1.0+ + + If you are using a + replica set and version + 1.1.0 or above of the driver, the driver can automatically route reads to + slaves. This behavior does not exist in earlier versions of the driver and + cannot be used with "normal" master-slave. + + + + + By default, the driver will send all queries to the master. If you set the + "slaveOkay" option, the driver will send all queries to a non-primary server, + if possible. The "slaveOkay" option can be set at every "level": + connection, + database, + collection, and + cursor. Each class inherits the + "slaveOkay" setting from the class above it, so if you do: + + + +setSlaveOkay(true); +$c = $db->myCollection; + +$cursor = $c->find(); + +?> +]]> + + + + then the query will be executed against a slave (the collection inherited + "slaveOkay" from the database and the cursor inherited it from the + collection). + + +
+ How slaves are chosen + + + Each instance of Mongo gets its own slave, randomly + chosen from the readable slaves. This holds, even if you are using + persistent connections. So, if we do something like: + + + true, "persist" => "x")); +echo "m1's slave is ".$m1->getSlave()."\n"; + +// uses the same connection as $m1 +$m2 = new Mongo("mongodb://ip0", array("replicaSet" => true, "persist" => "x")); +echo "m2's slave is ".$m2->getSlave()."\n"; + +?> +]]> + + + we'd probably end up with something like: + + +m1's slave is: ip2 +m2's slave is: ip1 + + + + If we continued to create new Mongos, we should get a + fairly even distribution between ip1 and ip2. + + + + Slaves are chosen on a per-instance basis and do no change (unless something + bad happens to your set and they are forced to). + + + + You can see what the driver thinks is the current status of the set members + by running Mongo::getHosts. + + + + If no non-primary server is readable, the driver will send + reads to the primary (even if "slaveOkay" is set). A server is considered + readable if its state is 2 (SECONDARY) and its health is 1. You can check + this with Mongo::getHosts (some fields omitted for + clarity): + + + Array + ( + [_id] => 0 + [name] => ip0 + [health] => 1 + [state] => 1 + [stateStr] => PRIMARY + ) + + [ubuntu:27019] => Array + ( + [_id] => 2 + [name] => ip1 + [health] => 1 + [state] => 2 + [stateStr] => SECONDARY + ) + + [ubuntu:27018] => Array + ( + [_id] => 1 + [name] => ip2 + [health] => 1 + [state] => 2 + [stateStr] => SECONDARY + ) + +) +]]> + + + The set above has two readable servers, "ip1" and "ip2". If both of + these went down or became stale, reads would go to "ip0". + + + + If you enjoy twiddling knobs that you probably shouldn't mess with, you can + force the driver to use a different slave by calling + Mongo::switchSlave. This randomly chooses a new slave + to use and shouldn't be used unless you know what you're doing. + + +
+
+ Random notes + + + Writes are always sent to the primary. Database commands, even read-only + commands, are also always sent to the primary. + + + + The health and state of a slave is checked every 5 seconds or when the next + operation occurs after 5 seconds. It will also recheck the configuration + when the driver has a problem reaching a server. You can manually force the + driver to update the status by calling Mongo::getHosts. + + + + Note that a non-primary server may be behind the primary in operations, so + your application must be okay with getting out-of-date data (or you must use + w for all writes). + +
+ +
+
Querying by _id diff --git a/reference/mongo/versions.xml b/reference/mongo/versions.xml index 2a5f4af323..b907298895 100644 --- a/reference/mongo/versions.xml +++ b/reference/mongo/versions.xml @@ -18,6 +18,11 @@ + + + + + @@ -41,6 +46,8 @@ + + @@ -63,6 +70,8 @@ + +