From 3eff93c56102c0f035a2ffc858bbc8027a212968 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 5 Nov 2012 10:20:11 -0500 Subject: [PATCH 1/3] DOCS-501 new connections document --- draft/administration/connections.txt | 388 +++++++++++++++++++++++++++ 1 file changed, 388 insertions(+) create mode 100644 draft/administration/connections.txt 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 From 13d92471b9e6fc2b1e2b615b8cf42fb600093cdb Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 14 Nov 2012 13:48:40 -0500 Subject: [PATCH 2/3] DOCS-501 review edits --- draft/administration/connections.txt | 134 ++++++++++++++------------- 1 file changed, 70 insertions(+), 64 deletions(-) diff --git a/draft/administration/connections.txt b/draft/administration/connections.txt index 2b3488443cd..d7238b51989 100644 --- a/draft/administration/connections.txt +++ b/draft/administration/connections.txt @@ -12,12 +12,16 @@ 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 +operation during the lifetime of the connection. +A single connection object can represent multiple connections to +multiple :program:`mongod` or :program:`mongos` instances. + +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 +The 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 +Beginning with the Fall 2012 driver releases, MongoDB uses two new connection classes for the creation of connection objects: - ``MongoClient``: the standard connection class @@ -27,24 +31,24 @@ the creation of connection objects: 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 +In MongoDB versions prior to the Fall 2012 driver releases, 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 +When you start a :program:`mongod` or :program:`mongos` instance, +the program displays logging information and then displays that it is waiting for a client -connections, as shown in the following example. +connection, 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. +By default, MongoDB waits for connections on port 27017. + +You make socket connections to running :program:`mongod` or :program:`mongos` instances +through a MongoDB :doc:`driver ` or +through the :program:`mongo` shell. .. note:: You *cannot* create a connection through HTTP on port 27017. Specifically, you *cannot* connect to MongoDB by going to @@ -67,8 +71,8 @@ The following is the standard URI connection scheme: 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: +.. example:: In the following example, a connection + logs into two members in the ``test`` replica set: .. code-block:: none @@ -118,8 +122,8 @@ 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. +.. example:: In the following example, a connection + uses the ``replicaSet`` and ``connectTimeoutMS`` options. .. code-block:: none @@ -128,31 +132,40 @@ is deprecated. Replica Set Options ~~~~~~~~~~~~~~~~~~~ -.. data:: replicaSet= +.. data:: replicaSet - If the :program:`mongod` is a member of a :term:`replica set`, the - name of the replica set. + Specifies the name of the :term:`replica set`, if the + :program:`mongod` is a member of a replica set. + + When connecting to a replica set it is important to give a seed list + of at least two :program:`mongod` instances. Connection Options ~~~~~~~~~~~~~~~~~~ -.. data:: ssl= +.. 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. + .. todo Determine whether ``prefer`` option exists. Check with server + team whether it's possible to do rolling restarts of a cluster to + turn on SSL. Here is the option + ``prefer``: Initiate the connection with SSL, but if that fails initiate without SSL. The default value is ``false``. -.. data:: connectTimeoutMS= + .. note:: The :data:`ssl` option is not supported by all drivers. For information on your + driver, see the :doc:`drivers ` documentation. + +.. 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= +.. 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 @@ -168,29 +181,33 @@ Most drivers handle this for you behind the scenes. Some drivers do not support connection pools. See the :doc:`/applications/drivers` documentation. -.. data:: maxPoolSize= +.. data:: maxPoolSize The maximum number of connections in the connection pool. The default value is ``100``. -.. data:: minPoolSize= +.. data:: minPoolSize - The minimum number of connections in the connection pool The default + The minimum number of connections in the connection pool. The default value is ``0``. -.. data:: maxIdleTimeMS= + .. note:: The :data:`minPoolSize` option is not supported by all + drivers. For information on your driver, see the :doc:`drivers + ` documentation. + +.. data:: maxIdleTimeMS The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed. -.. data:: waitQueueMultiple= +.. 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= +.. data:: waitQueueTimeoutMS The maximum time in milliseconds that a thread is allowed to wait for a connection to become available. For @@ -199,28 +216,15 @@ documentation. Write Concern Options ~~~~~~~~~~~~~~~~~~~~~ -.. data:: fireAndForget= - - ``false``: Sends a :dbcommand:`getLastError` command after - every update to ensure that the update succeeded. +For a full explanation of write concern, see +:ref:`write-operations-write-concern`. - ``true``: Does not send a :dbcommand:`getLastError` command after - every update. +.. data:: w - 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. + Used by the :dbcommand:`getLastError` command either to configure + write concern on members of :term:`replica sets ` *or* + to disable write concern entirely. This option can take either a + number or a string as a value. ``0``: Disables write concern. If you disable write concern but enable the :dbcommand:`getLastError` command's ``journal`` option, the @@ -233,24 +237,20 @@ Write Concern Options 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. + non-existent members become available, which means the write + operation 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= +.. data:: wtimeoutMS The time in milliseconds to wait for replication to succeed, as specified in the ``w`` option, before timing out. -.. data:: journal= +.. data:: journal ``true``: Sync to journal. @@ -270,12 +270,10 @@ Write Concern Options Read Preference Options ~~~~~~~~~~~~~~~~~~~~~~~ -.. data:: slaveOk= +For a full explanation of read preferences, see +:ref:`replica-set-read-preference`. - Specifies whether a driver connected to a replica set sends reads - to secondaries. The default setting is ``false``. - -.. data:: readPreference= +.. data:: readPreference Specifies the :term:`replica set` read preference for this connection. This setting overrides any ``slaveOk`` value. The read @@ -293,7 +291,7 @@ Read Preference Options The default value is :readmode:`primary`, which sends all read operations to the replica set's :term:`primary`. -.. data:: readPreferenceTags= +.. data:: readPreferenceTags Specifies a tag set as a comma-separated list of colon-separated key-value pairs. For example: @@ -314,7 +312,7 @@ Read Preference Options Miscellaneous Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. data:: uuidRepresentation= +.. data:: uuidRepresentation ``standard``: The standard binary representation. @@ -327,6 +325,10 @@ Miscellaneous Configuration For the default, see the :doc:`drivers ` documentation for your driver. + .. note:: The :data:`uuidRepresentation` option is not supported by + all drivers. For information on your driver, see the :doc:`drivers + ` documentation. + .. _connections-connection-examples: Examples @@ -354,6 +356,10 @@ password ``moon``: Connect to a UNIX domain socket: +.. note:: Not all drivers support UNIX domain sockets. For information + on your driver, see the :doc:`drivers ` + documentation. + .. code-block:: none mongodb:///tmp/mongodb-27017.sock From 04e35c6ee46d588d70528ed9c2f8f80fe1c70fa4 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 14 Nov 2012 14:02:17 -0500 Subject: [PATCH 3/3] DOCS-501 delete lines 13 - 55 --- draft/administration/connections.txt | 44 ---------------------------- 1 file changed, 44 deletions(-) diff --git a/draft/administration/connections.txt b/draft/administration/connections.txt index d7238b51989..8cd2e6f4e5c 100644 --- a/draft/administration/connections.txt +++ b/draft/administration/connections.txt @@ -10,50 +10,6 @@ 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. -A single connection object can represent multiple connections to -multiple :program:`mongod` or :program:`mongos` instances. - -The connection object -uses the options you specify when creating the connection. -The reuse of the connection object saves on the costs of setup and -teardown on connections. - -Beginning with the Fall 2012 driver releases, 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 releases, the connection classes vary from driver -to driver. - -When you start a :program:`mongod` or :program:`mongos` instance, -the program displays logging -information and then displays that it is waiting for a client -connection, 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. - -You make socket connections to running :program:`mongod` or :program:`mongos` instances -through a MongoDB :doc:`driver ` or -through the :program:`mongo` shell. - -.. 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: