<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="advanced-connections">

  <title>Advanced Connections</title>

  <p>
    The following sections contain information specific to certain types of MongoDB configurations.
    You may not need to use all of them, but understanding their uses is a good idea.
  </p>

  <section id="ssl">
    <info>
      <link type="guide" xref="index#advanced-connections" />
    </info>
    <title>Connecting over SSL</title>
    <p>
      To connect to a MongoDB server enabled with SSL, simply provide the <code>?ssl=true</code> option in the MongoDB URI.
    </p>
    <code mime="text/x-csrc">"mongodb://localhost:27017/?ssl=true"</code>
    <note style="important">
      <p>
        If the MongoDB C Driver has not been compiled with <code>--enable-ssl</code>, then connecting to a server that does not support SSL will fail if the <code>?ssl=true</code> parameter is provided in the URI.
        This is to prevent unintentional information leak.
      </p>
    </note>
  </section>

  <section id="replica-set">
    <info>
      <link type="guide" xref="index#advanced-connections" />
    </info>

    <title>Connecting to a Replica Set</title>

    <p>
      Connecting to a <link href="http://docs.mongodb.org/manual/replication/">Replica Set</link> is much like connecting to a single MongoDB server.
      All that is needed is to alter the connection string URI.
      The following listing will connect to a Replica Set named <code>myreplset</code>.
      The hostname <code>myreplset01</code> should be a member of the configured Replica Set.
      Notice the addition of <code>replicaSet=myreplset</code>.
    </p>

    <code mime="text/x-csrc"><![CDATA[#include <bson.h>
#include <mongoc.h>

int
main (int   argc,
      char *argv[])
{
    mongoc_client_t *client;

    mongoc_init ();

    /* Create our MongoDB Client */
    client = mongoc_client_new ("mongodb://myreplset01:27017/?replicaSet=myreplset");

    /* do something with client ... */

    /* Free our client */
    mongoc_client_destroy (client);

    mongoc_cleanup ();

    return 0;
}
]]></code>

    <note style="advanced">
      <p>
        You can specify multiple hostnames using the MongoDB connection string URI.
        The Mongo C Driver will use this information to try to recover in the case of a <link href="http://en.wikipedia.org/wiki/Network_partition">network partition</link>.
      </p>
    </note>

    <p>
      To seed a list of nodes in your Replica Set, use a comma to separate the hostnames.
    </p>

    <code mime="text/x-csrc">"mongodb://myreplset01:27017,myreplset02:27017/?replicaSet=myreplset"</code>
      
  </section>

  <section id="sharded-cluster">
    <info>
      <link type="guide" xref="index#advanced-connections" />
    </info>

    <title>Connecting to a Sharded Cluster</title>

    <p>
      The MongoDB C Driver will automatically detect if it has connected to a <code>mongos</code> sharding server.
      You can specify a URI just like you would for connecting directly to a single MongoDB server.
      If you specify more than one hostname a seed list will be created to attempt to handle failover between the <code>mongos</code> instances.
    </p>

    <code mime="text/x-csrc"><![CDATA[#include <bson.h>
#include <mongoc.h>

int
main (int   argc,
      char *argv[])
{
    mongoc_client_t *client;

    mongoc_init ();

    /* Create our MongoDB Client */
    client = mongoc_client_new ("mongodb://myshard01:27017/");

    /* Do something with client ... */

    /* Free the client */
    mongoc_client_destroy (client);

    mongoc_cleanup ();

    return 0;
}
]]></code>

    <note style="important">
      <p>
        Specifying the <code>replicaSet</code> parameter when connecting to a <code>mongos</code> sharding server is invalid.
      </p>
    </note>

  </section>

  <section id="unix-socket">
    <info>
      <link type="guide" xref="index#advanced-connections" />
    </info>

    <title>Connecting to a UNIX Domain Socket</title>

    <p>
      On UNIX-like systems, you can connect directly to a MongoDB server using a UNIX domain socket.
      Use the following URI format to specify the path to the socket.
      The socket path <em>MUST</em> be suffixed with <code>.sock</code>.
    </p>

    <code mime="text/x-csrc">"mongodb:///tmp/mongodb-27017.sock"</code>

    <note style="warning">
      <p>Connecting directly to a UNIX domain socket is not a common practice.</p>
    </note>
  </section>

</page>
