svn: /phpdoc/en/trunk/reference/mongo/ connecting.xml mongoconnectionexception.xml

From: 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 =&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> <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>

« previous php.doc.cvs (#7043) next »