DOCS-398 Connections document: early draft

draft/administration/connections.txt

@@ -0,0 +1,388 @@
+.. index:: connections
+
+===========
+Connections
+===========
+
+.. default-domain:: mongodb
+
+This document describes the URI format for defining connections between
+applications and MongoDB instances in the official MongoDB :doc:`drivers
+</applications/drivers>`.
+
+When you connect to a MongoDB database server, the MongoDB driver creates a
+connection object that is instantiated once and then reused for every
+operation during the lifetime of the connection. The connection object
+uses the options you specify when creating the connection.
+The driver's reuse of the connection object saves on the costs of setup and
+teardown on connections.
+
+Beginning with the Fall 2012 driver release, MongoDB uses two new connection classes for
+the creation of connection objects:
+
+- ``MongoClient``: the standard connection class
+
+- ``MongoReplicaSetClient``: a connection class that some drivers use
+  separately for :term:`replica sets <replica set>`. Not all drivers use
+  a separate class for connections to replica sets. See the
+  :doc:`drivers </applications/drivers>` documentation for details.
+
+In MongoDB versions prior to the Fall 2012 driver release, the connection classes vary from driver
+to driver.
+
+You connect to a MongoDB database server by starting a :program:`mongod`
+instance through a MongoDB :doc:`driver </applications/drivers>` or
+through the :program:`mongo` shell.
+
+Upon connection to the server, :program:`mongod` displays logging
+information and then displays that it is waiting for a client
+connections, as shown in the following example.
+
+.. code-block:: none
+
+   Wed Nov 21 12:56:58 [websvr] admin web console waiting for connections on port 28017
+   Wed Nov 21 12:56:58 [initandlisten] waiting for connections on port 27017
+
+By default, MongoDB waits for connections on port 27017. The
+:program:`mongod` program runs in either the foreground or background.
+
+.. note:: You *cannot* create a connection through HTTP on port 27017.
+   Specifically, you *cannot* connect to MongoDB by going to
+   ``http://localhost:27017`` in your web browser.
+
+.. index:: connections; connection string format
+.. _connections-standard-connection-string-format:
+
+Standard Connection String Format
+---------------------------------
+
+This section describes the standard format of the MongoDB connection URI
+used to connect to a MongoDB database server. The format is the same for
+all official MongoDB drivers. For a list of drivers and links to driver
+documentation, see :doc:`/applications/drivers`.
+
+The following is the standard URI connection scheme:
+
+.. code-block:: none
+
+   mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]
+
+.. example:: In the following example, a connection issued from a Java
+   driver logs into two databases in the ``test`` replica set:
+
+   .. code-block:: none
+
+      mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test
+
+- ``mongodb:// `` is a required prefix to identify that this is a string
+  in the standard connection format.
+
+- ``username:password@`` are optional. If they are given,
+  :program:`mongod` attempts to log in to a specific database after
+  connecting to a database server.
+
+- ``host1`` is the only required part of the URI. It identifies a server
+  address to connect to. It identifies either a hostname, IP address, or
+  UNIX domain socket.
+
+- ``:port1`` is optional and defaults to ``:27017`` if not provided.
+
+- ``hostX`` is optional. You can specify as many hosts as necessary. You
+  would specify multiple hosts, for example, for connections to replica
+  sets.
+
+- ``:portX`` is optional and defaults to ``:27017`` if not provided.
+
+- ``/database`` is the name of the database to log in to. This is
+  relevant only if the ``username:password@`` syntax is used. If
+  ``/database`` is not specified, the ``admin`` database is used by
+  default.
+
+- ``?options`` are connection options, as described in
+  :ref:`connections-connection-options`.
+
+  If the ``database`` string is absent you must still have a ``/``
+  between the last ``hostN`` and the ``?`` introducing the options.
+
+.. index:: connections; options
+.. _connections-connection-options:
+
+Connection Options
+------------------
+
+The connection options used in the
+:ref:`connections-standard-connection-string-format` are listed in this
+section. The options are not case-sensitive.
+
+Connection options are name=value pairs. The pairs are separated by "&".
+For backwards compatibility, ``;`` is accepted as a separator. But ``;``
+is deprecated.
+
+.. example:: In the following example, a connection issued from a Java
+   driver uses the ``replicaSet`` and ``connectTimeoutMS`` options.
+
+   .. code-block:: none
+
+      mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test&connectTimeoutMS=300000
+
+Replica Set Options
+~~~~~~~~~~~~~~~~~~~
+
+.. data:: replicaSet=<name>
+
+   If the :program:`mongod` is a member of a :term:`replica set`, the
+   name of the replica set.
+
+Connection Options
+~~~~~~~~~~~~~~~~~~
+
+.. data:: ssl=<true,false,prefer>
+
+   ``true``: Initiate the connection with SSL.
+
+   ``false``: Initiate the connection without SSL.
+
+   ``prefer``: Initiate the connection with SSL, but if that fails initiate without SSL.
+
+   The default value is ``false``.
+
+.. data:: connectTimeoutMS=<milliseconds>
+
+   The time in milliseconds to attempt a connection before timing out.
+   The default is never to timeout, though different drivers might vary.
+   See the :doc:`/applications/drivers` documentation.
+
+.. data:: socketTimeoutMS=<milliseconds>
+
+   The time in milliseconds to attempt a send or receive on a socket
+   before the attempt times out. The default is never to timeout, though
+   different drivers might vary. See the :doc:`/applications/drivers`
+   documentation.
+
+Connection Pool Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The server uses one thread per TCP connection, therefore it is highly
+recommended that your application use some sort of connection pooling.
+Most drivers handle this for you behind the scenes. Some drivers do not
+support connection pools. See the :doc:`/applications/drivers`
+documentation.
+
+.. data:: maxPoolSize=<number>
+
+   The maximum number of connections in the connection pool. The default
+   value is ``100``.
+
+.. data:: minPoolSize=<number>
+
+   The minimum number of connections in the connection pool The default
+   value is ``0``.
+
+.. data:: maxIdleTimeMS=<milliseconds>
+
+   The maximum number of milliseconds that a connection can remain idle
+   in the pool before being removed and closed.
+
+.. data:: waitQueueMultiple=<milliseconds>
+
+   A multiplier number that is multiplied with the
+   ``maxPoolSize`` setting to give the maximum number of threads allowed
+   to wait for a connection to become available from the pool. For
+   default values, see the :doc:`/applications/drivers` documentation.
+
+.. data:: waitQueueTimeoutMS=<milliseconds>
+
+   The maximum time in milliseconds that a thread is allowed to wait for
+   a connection to become available. For
+   default values, see the :doc:`/applications/drivers` documentation.
+
+Write Concern Options
+~~~~~~~~~~~~~~~~~~~~~
+
+.. data:: fireAndForget=<true|false>
+
+   ``false``: Sends a :dbcommand:`getLastError` command after
+   every update to ensure that the update succeeded.
+
+   ``true``: Does not send a :dbcommand:`getLastError` command after
+   every update.
+
+   The default value depends on the connection class. Prior to the Fall
+   2012 driver release, the default value is ``true``, which disables
+   write concern. For the ``MongoClient`` and ``MongoReplicaSetClient``
+   classes new in the Fall 2012 driver release the default is ``false``.
+
+   For the new ``MongoClient`` and ``MongoReplicaSetClient`` classes, if
+   you enable ``fireAndForget`` but also enable write concern through
+   the ``w`` option, MongoDB issues an exception about the conflict.
+
+.. data:: w=<number or string>
+
+   Used by the :dbcommand:`getLastError` command either
+   to configure write concern on members of :term:`replica sets <replica
+   set>` *or* to disable write concern entirely.
+
+   ``0``: Disables write concern. If you disable write concern but
+   enable the :dbcommand:`getLastError` command's ``journal`` option, the
+   journal option prevails and write concern with journaling is enabled.
+
+   ``1``: Enables write concern on a standalone :program:`mongod` or the
+    :term:`primary` in a replica set. *This is the default setting.*
+
+   *A number greater than 1*: Confirms that write operations have
+   replicated to the specified number of replica set members, including
+   the primary. If you set ``w`` to a number that is greater than the
+   number of set members that hold data, MongoDB waits for the
+   non-existent members become available, which means MongoDB blocks
+   indefinitely.
+
+   ``majority``: Confirms that write operations have replicated to the
+   majority of set members.
+
+   ``-1``: Turns off reporting of network errors.
+
+   For the new ``MongoClient`` and ``MongoReplicaSetClient`` classes, if
+   you enable write concern but also enable ``fireAndForget``, MongoDB
+   issues an exception about the conflict.
+
+.. data:: wtimeoutMS=<milliseconds>
+
+   The time in milliseconds to wait for replication to succeed, as
+   specified in the ``w`` option, before timing out.
+
+.. data:: journal=<true|false>
+
+   ``true``: Sync to journal.
+
+   Confirm that the :program:`mongod` instance has written the data to
+   the on-disk journal. This is equivalent to specifying the
+   :dbcommand:`getLastError` command with the ``j`` option enabled.
+
+    ``false``: Does not confirm that data is written to the on-disk
+    journal.
+
+    The default value is ``false``.
+
+    If you enable the ``journal``option but have not enabled write concern through
+    the ``w`` option, the journal option prevails and write concern with
+    journaling is enabled.
+
+Read Preference Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. data:: slaveOk=<true|false>
+
+   Specifies whether a driver connected to a replica set sends reads
+   to secondaries. The default setting is ``false``.
+
+.. data:: readPreference=<string>
+
+   Specifies the :term:`replica set` read preference for this
+   connection. This setting overrides any ``slaveOk`` value. The read
+   preference values are the following:
+
+   - :readmode:`primary`
+   - :readmode:`primaryPreferred`
+   - :readmode:`secondary`
+   - :readmode:`secondaryPreferred`
+   - :readmode:`nearest`
+
+   For descriptions of each value, see
+   :ref:`replica-set-read-preference-modes`.
+
+   The default value is :readmode:`primary`, which sends all read
+   operations to the replica set's :term:`primary`.
+
+.. data:: readPreferenceTags=<string>
+
+   Specifies a tag set as a comma-separated list of
+   colon-separated key-value pairs. For example:
+
+   .. code-block:: none
+
+      dc:ny,rack:1
+
+   To specify a *list* of tag sets, use multiple ``readPreferenceTags``.
+   The following specifies two tag sets and an empty tag set:
+
+   .. code-block:: none
+
+      readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=
+
+   Order matters when using multiple ``readPreferenceTags``.
+
+Miscellaneous Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. data:: uuidRepresentation=<string>
+
+   ``standard``: The standard binary representation.
+
+   ``csharpLegacy``: The default representation for the C# driver.
+
+   ``javaLegacy``: The default representation for the Java driver.
+
+   ``pythonLegacy``: The default representation for the Python driver.
+
+   For the default, see the :doc:`drivers </applications/drivers>`
+   documentation for your driver.
+
+.. _connections-connection-examples:
+
+Examples
+--------
+
+Connect to a database server running locally on the default port:
+
+.. code-block:: none
+
+   mongodb://localhost
+
+Connect and log in to the ``admin`` database as user ``rachel`` with
+password ``moon``:
+
+.. code-block:: none
+
+   mongodb://rachel:moon@localhost
+
+Connect and log in to the ``baz`` database as user ``rachel`` with
+password ``moon``:
+
+.. code-block:: none
+
+   mongodb://rachel:moon@localhost/baz
+
+Connect to a UNIX domain socket:
+
+.. code-block:: none
+
+   mongodb:///tmp/mongodb-27017.sock
+
+Connect to a :term:`replica set` with two members, one on
+``example1.com`` and the other on ``example2.com``:
+
+.. code-block:: none
+
+   mongodb://example1.com:27017,example2.com:27017
+
+Connect to a replica set with three members running on ``localhost``, on
+ports 27017, 27018 and 27019:
+
+.. code-block:: none
+
+   mongodb://localhost,localhost:27018,localhost:27019
+
+Connect to a replica set with three members. Send all writes to the
+:term:`primary` and distribute reads to the :term:`secondaries <secondary>`:
+
+.. code-block:: none
+
+   mongodb://example1.com,example2.com,example3.com/?slaveOk=true
+
+Connect to a replica set with write concern configured to wait for
+replication to succeed on at least two members, with a two-second
+timeout.
+
+.. code-block:: none
+
+   mongodb://example1.com,example2.com,example3.com/?w=2&wtimeoutMS=2000