diff --git a/draft/administration/connections.txt b/draft/administration/connections.txt new file mode 100644 index 00000000000..2b3488443cd --- /dev/null +++ b/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 +`. + +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 `. Not all drivers use + a separate class for connections to replica sets. See the + :doc:`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 ` 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= + + If the :program:`mongod` is a member of a :term:`replica set`, the + name of the replica set. + +Connection Options +~~~~~~~~~~~~~~~~~~ + +.. data:: ssl= + + ``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= + + 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= + + 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= + + The maximum number of connections in the connection pool. The default + value is ``100``. + +.. data:: minPoolSize= + + The minimum number of connections in the connection pool The default + value is ``0``. + +.. data:: maxIdleTimeMS= + + The maximum number of milliseconds that a connection can remain idle + in the pool before being removed and closed. + +.. data:: waitQueueMultiple= + + 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= + + 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= + + ``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= + + Used by the :dbcommand:`getLastError` command either + to configure write concern on members of :term:`replica sets ` *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= + + The time in milliseconds to wait for replication to succeed, as + specified in the ``w`` option, before timing out. + +.. data:: journal= + + ``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= + + Specifies whether a driver connected to a replica set sends reads + to secondaries. The default setting is ``false``. + +.. data:: readPreference= + + 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= + + 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= + + ``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 ` + 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 `: + +.. 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