From 14bd490d6de3af8baf5e9614f0a2c6934f8e4d1b Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 31 Oct 2012 14:15:09 -0400 Subject: [PATCH 1/6] DOCS-398 create new connections document --- draft/administration/connections.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 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..ad6d2e036a1 --- /dev/null +++ b/draft/administration/connections.txt @@ -0,0 +1,26 @@ +=========== +Connections +=========== + +.. default-domain:: mongodb + +MongoDB is a database server. When you connect to MongoDB, MongoDB +creates a connection object. The connection object is instantiated once +and then reused for every operation during the lifetime of the +connection. This saves on the costs of setup and teardown on +connections. + +You create a connection by starting the :program:`mongod` program. +The :program:`mongod` program then runs in the foreground or background +and waits for connections from the user. + +When you start :program:`mongod`, MongoDB displays logging information +and then waits for a connection, as shown in the following example. + +.. code-block:: sh + + Last login: Wed Nov 21 12:56:06 on ttys000 + mymachine:smith smith$ mongod --port 27017 --dbpath /data/db Wed Nov 21 12:56:57 [initandlisten] MongoDB starting : pid=215 port=27017 dbpath=/data/db 64-bit host=smith + ** + 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 From 9f362fdf5775880016127932657800c280f63fa4 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 31 Oct 2012 19:59:25 -0400 Subject: [PATCH 2/6] DOCS-398 connections document: majority of the first draft written --- draft/administration/connections.txt | 211 +++++++++++++++++++++++++-- 1 file changed, 198 insertions(+), 13 deletions(-) diff --git a/draft/administration/connections.txt b/draft/administration/connections.txt index ad6d2e036a1..71b116ad32c 100644 --- a/draft/administration/connections.txt +++ b/draft/administration/connections.txt @@ -1,26 +1,211 @@ +.. index:: connections + =========== Connections =========== .. default-domain:: mongodb -MongoDB is a database server. When you connect to MongoDB, MongoDB -creates a connection object. The connection object is instantiated once -and then reused for every operation during the lifetime of the -connection. This saves on the costs of setup and teardown on -connections. +This document describes the URI :ref:`format +` and :ref:`options +` for creating a connection to a MongoDB +database server. + +When you connect to a MongoDB database server, MongoDB 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 connection options you specify when creating the connection. +MongoDB's reuse of the connection object saves on the costs of setup and +teardown on connections. -You create a connection by starting the :program:`mongod` program. -The :program:`mongod` program then runs in the foreground or background -and waits for connections from the user. +You connect to a MongoDB database server by starting a :program:`mongod` +instance through a MongoDB :doc:`driver ` or +through the :program:`mongo` shell. -When you start :program:`mongod`, MongoDB displays logging information -and then waits for a connection, as shown in the following example. +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:: sh - Last login: Wed Nov 21 12:56:06 on ttys000 - mymachine:smith smith$ mongod --port 27017 --dbpath /data/db Wed Nov 21 12:56:57 [initandlisten] MongoDB starting : pid=215 port=27017 dbpath=/data/db 64-bit host=smith - ** 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:: sh + + mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]] + +- ``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. + + Options are name=value pairs. The pairs are separated by "&". For + backwards compatibility, ``;`` is accepted as a separator but should + be considered as deprecated. + +.. 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: + +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= + + This is 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 (see also ``w`` and + ``wtimeoutMS``). + + ``true``: Does not send a :dbcommand:`getLastError` command after + every update. + + Default value depends on the connection class. For the new + MongoClient classes, the default is ``false``. + +.. data:: w= + + This option is 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. Write concern is enabled with journaling. + + ``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. From 53e4973c3979d5717ff7927e57de2de9434f3bcb Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 1 Nov 2012 13:35:38 -0400 Subject: [PATCH 3/6] DOCS-398 connections document: complete first draft --- draft/administration/connections.txt | 192 ++++++++++++++++++++++++--- 1 file changed, 173 insertions(+), 19 deletions(-) diff --git a/draft/administration/connections.txt b/draft/administration/connections.txt index 71b116ad32c..a6624ec3e2b 100644 --- a/draft/administration/connections.txt +++ b/draft/administration/connections.txt @@ -6,16 +6,15 @@ Connections .. default-domain:: mongodb -This document describes the URI :ref:`format -` and :ref:`options -` for creating a connection to a MongoDB -database server. +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, MongoDB creates a +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 connection options you specify when creating the connection. -MongoDB's reuse of the connection object saves on the costs of setup and +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. You connect to a MongoDB database server by starting a :program:`mongod` @@ -26,7 +25,7 @@ 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:: sh +.. 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 @@ -51,10 +50,17 @@ documentation, see :doc:`/applications/drivers`. The following is the standard URI connection scheme: -.. code-block:: sh +.. 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. @@ -85,10 +91,6 @@ The following is the standard URI connection scheme: If the ``database`` string is absent you must still have a ``/`` between the last ``hostN`` and the ``?`` introducing the options. - Options are name=value pairs. The pairs are separated by "&". For - backwards compatibility, ``;`` is accepted as a separator but should - be considered as deprecated. - .. index:: connections; options .. _connections-connection-options: @@ -97,7 +99,18 @@ 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: +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 ~~~~~~~~~~~~~~~~~~~ @@ -159,7 +172,7 @@ documentation. .. data:: waitQueueMultiple= - This is a multiplier number that is multiplied with the + 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. @@ -176,18 +189,17 @@ Write Concern Options .. data:: fireAndForget= ``false``: Sends a :dbcommand:`getLastError` command after - every update to ensure that the update succeeded (see also ``w`` and - ``wtimeoutMS``). + every update to ensure that the update succeeded. ``true``: Does not send a :dbcommand:`getLastError` command after every update. Default value depends on the connection class. For the new - MongoClient classes, the default is ``false``. + ``MongoClient`` classes, the default is ``false``. .. data:: w= - This option is used by the :dbcommand:`getLastError` command either + Used by the :dbcommand:`getLastError` command either to configure write concern on members of :term:`replica sets ` *or* to disable write concern entirely. @@ -209,3 +221,145 @@ Write Concern Options majority of set members. ``-1``: Turns off reporting of network errors. + + +.. 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 ``fireAndForget`` but also enable a write concern option, +MongoDB issues an exception about the conflict. + +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 ``fred`` with password +``foobar``: + +.. code-block:: none + + mongodb://fred:foobar@localhost + +Connect and log in to the ``baz`` database as user ``fred`` with password +``foobar``: + +.. code-block:: none + + mongodb://fred:foobar@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 d5b71f88ec0df30b8ce34434954fe4911aed7231 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 1 Nov 2012 14:24:55 -0400 Subject: [PATCH 4/6] DOCS-398 edits to clarify the two new classes --- draft/administration/connections.txt | 47 +++++++++++++++++++++------- 1 file changed, 35 insertions(+), 12 deletions(-) diff --git a/draft/administration/connections.txt b/draft/administration/connections.txt index a6624ec3e2b..27c75f579fb 100644 --- a/draft/administration/connections.txt +++ b/draft/administration/connections.txt @@ -17,6 +17,19 @@ 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 version 2.2, 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 2.2 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. @@ -194,8 +207,14 @@ Write Concern Options ``true``: Does not send a :dbcommand:`getLastError` command after every update. - Default value depends on the connection class. For the new - ``MongoClient`` classes, the default is ``false``. + The default value depends on the connection class. For connection + classes prior to version 2.2 the default value is ``true``, which + disables write concern. For the new ``MongoClient`` and + ``MongoReplicaSetClient`` classes, 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= @@ -204,8 +223,8 @@ Write Concern Options 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. Write concern is enabled with journaling. + 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.* @@ -222,6 +241,9 @@ Write Concern Options ``-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= @@ -241,8 +263,9 @@ Write Concern Options The default value is ``false``. -If you enable ``fireAndForget`` but also enable a write concern option, -MongoDB issues an exception about the conflict. + 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 ~~~~~~~~~~~~~~~~~~~~~~~ @@ -315,19 +338,19 @@ Connect to a database server running locally on the default port: mongodb://localhost -Connect and log in to the admin database as user ``fred`` with password -``foobar``: +Connect and log in to the ``admin`` database as user ``rachel`` with +password ``moon``: .. code-block:: none - mongodb://fred:foobar@localhost + mongodb://rachel:moon@localhost -Connect and log in to the ``baz`` database as user ``fred`` with password -``foobar``: +Connect and log in to the ``baz`` database as user ``rachel`` with +password ``moon``: .. code-block:: none - mongodb://fred:foobar@localhost/baz + mongodb://rachel:moon@localhost/baz Connect to a UNIX domain socket: From 6518a390c62dac683b11cfb15e763188ff7a16ca Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 1 Nov 2012 14:46:38 -0400 Subject: [PATCH 5/6] DOCS-398 term change: Fall 2012 driver release --- draft/administration/connections.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/draft/administration/connections.txt b/draft/administration/connections.txt index 27c75f579fb..db2422a029d 100644 --- a/draft/administration/connections.txt +++ b/draft/administration/connections.txt @@ -17,7 +17,7 @@ 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 version 2.2, MongoDB uses two new connection classes for +Beginning with the Fall 2012 driver release, MongoDB uses two new connection classes for the creation of connection objects: - ``MongoClient``: the standard connection class @@ -27,7 +27,7 @@ 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 2.2 the connection classes vary from driver +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` @@ -207,10 +207,10 @@ Write Concern Options ``true``: Does not send a :dbcommand:`getLastError` command after every update. - The default value depends on the connection class. For connection - classes prior to version 2.2 the default value is ``true``, which - disables write concern. For the new ``MongoClient`` and - ``MongoReplicaSetClient`` classes, the default is ``false``. + 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 From 6342892d3b53ed83b89b51168168dda9c880628c Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 5 Nov 2012 09:05:54 -0500 Subject: [PATCH 6/6] DOCS-398 typo --- draft/administration/connections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/administration/connections.txt b/draft/administration/connections.txt index db2422a029d..2b3488443cd 100644 --- a/draft/administration/connections.txt +++ b/draft/administration/connections.txt @@ -275,7 +275,7 @@ Read Preference Options 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