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;
+
+ publicarrayMongo::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;
+
+ publicstringMongo::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;
+
+ publicbooleanMongo::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;
+
+ publicbooleanMongo::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;
+
+ publicstringMongo::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;
+
+ publicbooleanMongoCollection::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;
+
+ publicbooleanMongoCollection::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::slaveOkaySets 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;
+
+ publicbooleanMongoDB::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;
+
+ publicbooleanMongoDB::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 @@
+
+