php-doc-en/reference/mongo/connecting.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<section xml:id="mongo.connecting" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Connecting</title>

 <para>
  Connecting to MongoDB can be as easy as <literal>new Mongo</literal>, but 
  there are many additional options and configurations. The 
  <function>Mongo::__construct</function> page covers all of the API options,
  but this page gives some more details and advice for practical use cases.
 </para>

 <section>
  <title>Logging In on Connection</title>
  <para>
   If MongoDB is started with the <literal>--auth</literal> option, connections
   must be authenticated before they are used.  You can do this on a 
   per-database level with <function>MongoDB::authenticate</function>:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo();
$db = $m->admin;

$db->authenticate($username, $password);

?>
]]>
  </programlisting>
  <para>
   There is a major disadvantage to this method: if the database connection is
   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 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 be authenticated automatically:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo("mongodb://${username}:${password}@localhost");

?>
]]>
  </programlisting>
  <para>
   By default, the driver will authenticate the user against the admin database.
   To authenticate with a different database, specify the database name after 
   the hosts.  This example will log the user into the "blog" database:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo("mongodb://${username}:${password}@localhost/blog");

?>
]]>
  </programlisting>
 </section>

 <section>
  <title>Replica Sets</title>
  <para>
   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", array("replicaSet" => true));

?>
]]>
  </programlisting>
  <para>
   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 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>
   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 sets, see the 
   <link xlink:href="&url.mongodb.replica;">core documentation</link>.
  </para>
 </section>

 <section>
  <title>Persistent Connections</title>

  <para>
   Creating new connection to the database is very slow.  To minimize the number
   of connections that you need to make, you can use persistent connections.  A 
   persistent connection is saved by PHP, so you can use the same connection for
   multiple requests.
  </para>

  <para>
   For example, this simple program connects to the database 1000 times:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

for ($i=0; $i<1000; $i++) {
  $m = new Mongo();
}

?>
]]>
  </programlisting>

  <para>
   It takes approximately 18 seconds to execute.  If we change it to use a 
   persistent connection:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

for ($i=0; $i<1000; $i++) {
  $m = new Mongo("localhost:27017", array("persist" => "x"));
}

?>
]]>
  </programlisting>

  <para>
   ...it takes less than .02 seconds to execute, as it only makes one database
   connection.
  </para>

  <para>
   Persistent connections need an identifier string (which is "x" in the above
   example) to uniquely identify them.  For a persistent connection to be used,
   the hostname, port, persist string, and username and password (if given) must
   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>
  <para>
   Persistent connections will become the default connection type in 1.0.12. To
   create a non-persistent connection, you will need to pass 
   <literal>"persist" =&gt; false</literal> to 
   <function>Mongo::__construct</function>.
  </para>
 </section>

 <section>
  <title>Domain Socket Support</title>

  <para>
   If you are running MongoDB locally and have version 1.0.9 or better of the 
   driver, you can connect to the database via file.  MongoDB automatically
   opens a socket file on startup: /tmp/mongodb-&lt;port&gt;.sock.
  </para>

  <para>
   To connect to the socket file, specify the path in your MongoDB connection 
   string:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo("mongodb:///tmp/mongo-27017.sock");

?>
]]>
  </programlisting>

  <para>
   If you would like to use authentication on connection (as described above)
   with a socket file, you must specify a port of 0 so that the connection
   string parser knows where the end of the connection string is.
  </para>

  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");

?>
]]>
  </programlisting>

 </section>

</section>