added replica set docs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@302812 c90b9560-bf6c-de11-be94-00142212c4b1

reference/mongo/connecting.xml

@@ -32,18 +32,16 @@ $db->authenticate($username, $password);
   </programlisting>
   <para>
    There is a major disadvantage to this method: if the database connection is
-   dropped and then autoreconnects, the connection will no longer be 
-   authenticated.
+   dropped and then reconnected, the connection will no longer be authenticated.
   </para>
   <para>
    If you use the connection string format described by 
-   <function>Mongo::__construct</function>, the database will authenticate the
-   connection as soon as it connects and reauthenticate if the connection is 
-   re-esetablished.
+   <function>Mongo::__construct</function>, the database will authenticate on
+   connection and reauthenticate if the connection is re-established.
   </para>
   <para>
    This is equivalent to the code above, except that reconnections to the 
-   database will automatically be authenticated:
+   database will be authenticated automatically:
   </para>
   <programlisting role="php">
 <![CDATA[
@@ -71,43 +69,84 @@ $m = new Mongo("mongodb://${username}:${password}@localhost/blog");
  </section>
 
  <section>
-  <title>Replica Pairs</title>
+  <title>Replica Sets</title>
   <para>
-   To connect to a replica pair, specify both sides of the pair.
+   To connect to a replica set, specify one or more members of the set and use
+   the <literal>replicaSet</literal> option.
   </para>
   <programlisting role="php">
 <![CDATA[
 <?php
 
-$m = new Mongo("mongodb://localhost:27017,localhost:27018");
+$m = new Mongo("mongodb://localhost:27017", array("replicaSet" => true));
 
 ?>
 ]]>
   </programlisting>
   <para>
-   Order is irrelevant, the PHP driver will query the database servers to figure
-   out which one is master.  So long as one of them is up and master, the 
-   connection will succeed.  If neither is up or there is no master, a 
+   Version 1.0.9+ of the driver is required to connect to a replica set 
+   (earlier versions of the driver will not autodetect the master or reconnect 
+   correctly).
+  </para>
+  <para>
+   The PHP driver will query the database server(s) listed to figure out who is
+   master.  So long as it can connect to at least one host listed and find a 
+   master, the connection will succeed.  If it cannot make a connection to any
+   servers listed or cannot find a master, a 
    <classname>MongoConnectionException</classname> will be thrown.
   </para>
   <para>
-   If the master becomes unavailable, the slave will not become master for a few
-   seconds.  During that time, the driver will not be able to perform any 
-   database operations because the master database is gone and the other 
-   database is a slave.  Thus, if you attempt to do any sort of query (including
-   "safe" operations) they will throw exceptions.
+   If the master becomes unavailable, the slaves will not promote a new master 
+   for a few seconds.  During that time, this connection will not be able to 
+   perform any database operations (connections to slaves will still be able to
+   perform reads).  Thus, if you attempt to do any sort of read or write on this
+   connection, it will throw an exception.
   </para>
   <para>
-   The slave will eventually realize that the master is gone and become master 
-   itself.  At this point, the driver will make this its primary database 
-   connection and continue operating normally.
+   Once a master is elected, attempting to perform a read or write will allow 
+   the driver to detect the new master. The driver will make this its primary 
+   database connection and continue operating normally.
   </para>
   <para>
-   For more information on replica pairs, see the 
+   For more information on replica sets, see the 
    <link xlink:href="&url.mongodb.replica;">core documentation</link>.
   </para>
  </section>
 
+ <section>
+  <title>Distributing Reads</title>
+  <para>
+   One way of using replica sets is to perform reads on the slaves to take some
+   load off of the master.  The driver will not do this automatically for you, 
+   but you can set it up yourself.
+  </para>
+  <para>
+   First, connect to the replica set using the <literal>replicaSet</literal>
+   option.  This will give you a connection to the replica set's master.  Use
+   this connection to call the <literal>ismaster</literal> command, which lists
+   all of the slaves in the replica set.
+  </para>
+  <programlisting role="php">
+<![CDATA[
+<?php
+
+$m = new Mongo("mongodb://localhost:27017", array("replicaSet" => true));
+$result = $m->admin->command(array("ismaster" => 1));
+
+?>
+]]>
+  </programlisting>
+  <para>
+   Now, create connections to the hosts listed in the "hosts" and "passives"
+   fields (passives are members of the set that can never become master).  Do 
+   not use <literal>replicaSet =&gt; true</literal>, or the driver will 
+   automatically find and use the master.)  Then you can distribute reads among 
+   these connections.  Make sure to set 
+   <literal>MongoCursor::slaveOkay</literal> to &true; before attempting to read
+   from a slave.
+  </para>
+ </section>
+
  <section>
   <title>Persistent Connections</title>
 
@@ -163,6 +202,12 @@ for ($i=0; $i<1000; $i++) {
    match an existing persistent connection.  Otherwise, a new connection will be
    created with this identifying information.
   </para>
+  <para>
+   Persistent connections are <emphasis>highly recommended</emphasis> and should
+   always be used in production unless there is a compelling reason not to.  
+   Most of the reasons that they are not recommended for relational databases 
+   are irrelevant to MongoDB.
+  </para>
  </section>
 
  <section>

reference/mongo/mongoconnectionexception.xml

@@ -52,6 +52,15 @@
       Connecting to the database timed out.
      </para>
     </listitem>
+    <listitem>
+     <para>
+      <literal>Transport endpoint is not connected</literal>
+     </para>
+     <para>
+      Generally means that the connection string isn't correct, the driver
+      couldn't even find the database server.
+     </para>
+    </listitem>
     <listitem>
      <para>
       <literal>couldn't determine master</literal>