svn: /phpdoc/en/trunk/reference/mongo/ connecting.xml mongoconnectionexception.xml
| From: | Kristina Chodorow | Date: | Thu, 26 Aug 2010 15:34:16 +0000 |
| Subject: | svn: /phpdoc/en/trunk/reference/mongo/ connecting.xml mongoconnectionexception.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-7043@lists.php.net to get a copy of this message | ||
kristina Thu, 26 Aug 2010 15:34:16 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=302812
Log:
added replica set docs
Changed paths:
U phpdoc/en/trunk/reference/mongo/connecting.xml
U phpdoc/en/trunk/reference/mongo/mongoconnectionexception.xml
Modified: phpdoc/en/trunk/reference/mongo/connecting.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/connecting.xml 2010-08-26 15:33:43 UTC (rev 302811)
+++ phpdoc/en/trunk/reference/mongo/connecting.xml 2010-08-26 15:34:16 UTC (rev 302812)
@@ -32,18 +32,16 @@
</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,44 +69,85 @@
</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 => 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>
<para>
@@ -163,6 +202,12 @@
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>
Modified: phpdoc/en/trunk/reference/mongo/mongoconnectionexception.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongoconnectionexception.xml 2010-08-26 15:33:43 UTC (rev
302811)
+++ phpdoc/en/trunk/reference/mongo/mongoconnectionexception.xml 2010-08-26 15:34:16 UTC (rev
302812)
@@ -54,6 +54,15 @@
</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>
</para>
<para>