diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 97fa3533a..f70abd878 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -1,8 +1,8 @@ .. _node-connection-pools: -================ -Connection Pools -================ +======================================== +Manage Connections with Connection Pools +======================================== .. facet:: :name: genre @@ -31,62 +31,167 @@ are created by {+driver-short+}. .. _node-faq-connection-pool: -Connection Pool Overview -------------------------- - -Every ``MongoClient`` instance has a built-in connection pool for each server -in your MongoDB topology. Connection pools open sockets on demand to -support concurrent requests to MongoDB in your application. - -The maximum size of each connection pool is set by the ``maxPoolSize`` option, which -defaults to ``100``. If the number of in-use connections to a server reaches -the value of ``maxPoolSize``, the next request to that server will wait -until a connection becomes available. - -In addition to the sockets needed to support your application's requests, -each ``MongoClient`` instance opens two more sockets per server -in your MongoDB topology for monitoring the server's state. -For example, a client connected to a three-node replica set opens six -monitoring sockets. If the application uses the default setting for -``maxPoolSize`` and only queries the primary (default) node, then -there can be at most ``106`` total connections in the connection pool. If the -application uses a :ref:`read preference ` to query the -secondary nodes, those connection pools grow and there can be -``306`` total connections. +Configure Connection Pools +-------------------------- + +Every ``MongoClient`` instance has a built-in connection pool for each server in +your MongoDB topology. If you do not configure the ``minPoolSize`` option, +connection pools open sockets on demand to support concurrent requests to +MongoDB in your application. + +You can specify the following connection pool settings in your ``MongoClient`` +instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Setting + - Description + + * - ``maxPoolSize`` + - | The maximum number of concurrent connections that the pool maintains. + If the number of in-use connections to a server reaches the specified + value, the next request to that server waits until a connection becomes + available. + | + | **Default**: ``100`` + + * - ``maxConnecting`` + - | The maximum number of connections that each pool can establish + concurrently. + + * - ``minPoolSize`` + - | The minimum number of concurrent connections that the pool maintains. + | + | **Default**: ``0`` + + * - ``maxIdleTimeMS`` + - | The maximum number of milliseconds that a connection can remain idle in + the pool. + | + | **Default**: ``0`` (no limit) + + * - ``waitQueueTimeoutMS`` + - | The maximum number of milliseconds that a request can wait for a socket + to become available. + | + | **Default**: ``0`` (no limit) + + +.. _node-connection-pool-max-pool-size: + +maxPoolSize +~~~~~~~~~~~ + +In addition to the sockets needed to support your application's requests, each +``MongoClient`` instance opens up to two connections per server in your +MongoDB topology for monitoring the server's state. + +For example, a client connected to a three-node replica set opens six monitoring +sockets. If the application uses the default setting for ``maxPoolSize`` and +only queries the primary (default) node, then there can be at most ``106`` open +sockets and ``100`` connections in the connection pool. If the application uses +a :ref:`read preference ` to query the secondary nodes, those +connection pools grow and there can be ``306`` total connections including the +open monitoring sockets. To support high numbers of concurrent MongoDB requests within one process, you can increase ``maxPoolSize``. -Connection pools are rate-limited. The ``maxConnecting`` option -determines the number of connections that the pool can create in -parallel at any time. For example, if the value of ``maxConnecting`` is -``2``, the third request that attempts to concurrently check out a -connection succeeds only when one the following cases occurs: +The following code creates a ``MongoClient`` instance with a maximum connection +pool size of ``200`` by specifying the ``maxPoolSize`` option in the +``options`` object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxPoolSize: 200 + }); + +.. _node-connection-pool-max-connecting: + +maxConnecting +~~~~~~~~~~~~~ + +Connection pools rate-limit connection establishment. The ``maxConnecting`` +option determines the number of connections that the pool can create in parallel +at any time. For example, if the value of ``maxConnecting`` is ``2``, the third +request that attempts to concurrently check out a connection succeeds only when +one the following cases occurs: - The connection pool finishes creating a connection and there are fewer than ``maxPoolSize`` connections in the pool. - An existing connection is checked back into the pool. -- The driver's ability to reuse existing connections improves due to - rate-limits on connection creation. -You can set the minimum number of concurrent connections to -each server with the ``minPoolSize`` option, which defaults to ``0``. -The driver initializes the connection pool with this number of sockets. If -sockets are closed, causing the total number -of sockets (both in use and idle) to drop below the minimum, more -sockets are opened until the minimum is reached. +The following code creates a ``MongoClient`` instance with a maximum number of +``2`` connections to be established concurrently per pool by specifying the +``maxConnecting`` option in the ``options`` object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxConnecting: 2 + }); + +.. _node-connection-pool-min-pool-size: + +minPoolSize +~~~~~~~~~~~ + +You can set the minimum number of connections to each server with the +``minPoolSize`` option. The driver ensures that there are always at least the +number of connections set by the ``minPoolSize`` option in the connection pool. +If sockets are closed, causing the total number of sockets (both in use and +idle) to drop below the minimum, more sockets are opened until the minimum is +reached. + +The following code creates a ``MongoClient`` instance with a minimum connnection +pool size of ``10`` by specifying the ``minPoolSize`` option in the ``options`` +object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + minPoolSize: 10 + }); + +.. _node-connection-pool-max-idle-time: + +maxIdleTimeMS +~~~~~~~~~~~~~ You can set the maximum number of milliseconds that a connection can remain idle in the pool by setting the ``maxIdleTimeMS`` option. Once a connection has been idle for ``maxIdleTimeMS``, the connection pool removes and replaces it. This option defaults to ``0`` (no limit). -The following default configuration for a ``MongoClient`` works for most -applications: +The following code creates a ``MongoClient`` instance with a maximum idle time +of ``10000`` milliseconds (10 seconds) by specifying the ``maxIdleTimeMS`` +setting in the ``options`` object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxIdleTimeMS: 10000 + }); + +.. _node-connection-pool-wait-queue-timeout: -.. code-block:: js - - const client = new MongoClient(""); +waitQueueTimeoutMS +~~~~~~~~~~~~~~~~~~ ``MongoClient`` supports multiple concurrent requests. For each process, create a client and reuse it for all operations in a process. This @@ -103,39 +208,72 @@ A request that waits more than the length of time defined by option if it is more important to bound the duration of operations during a load spike than it is to complete every operation. -When ``MongoClient.close()`` is called by any request, the driver -closes all idle sockets and closes all sockets that are in -use as they are returned to the pool. Calling ``MongoClient.close()`` -closes only inactive sockets and does not directly terminate -any ongoing operations. The driver closes any in-use sockets only when -the associated operations complete. However, the ``MongoClient.close()`` -method does close existing sessions and transactions, which might indirectly -affect the behavior of ongoing operations and open cursors. +The following code creates a ``MongoClient`` instance with a maximum wait queue +timeout of ``10000`` milliseconds (10 seconds) by declaring it in the +``options`` object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + waitQueueTimeoutMS: 10000 + }); + +Closing Connections +-------------------- + +When any request calls ``MongoClient.close()``, the {+driver-short+} performs +the following actions: + +- Closes all idle sockets in the connection pool +- Closes all sockets that are in use as they are returned to the pool +- Closes all sockets that are in use only when the associated operations + complete + +Calling ``MongoClient.close()`` closes only inactive sockets and does not +directly terminate any ongoing operations. + +.. note:: + + The ``MongoClient.close()`` method does close existing sessions and + transactions, which might indirectly affect the behavior of ongoing + operations and open cursors. Avoid Socket Timeouts --------------------- Having a large connection pool does not always reduce reconnection -requests. Consider the following example: +requests. Consider the following example scenario: -An application has a connection pool size of 5 sockets and has the -``socketTimeoutMS`` option set to 5000 milliseconds. Operations occur, -on average, every 3000 milliseconds, and reconnection requests are -frequent. Each socket times out after 5000 milliseconds, which means -that all sockets must do something during those 5000 milliseconds to -avoid closing. +- An application has a connection pool size of 5 sockets and has the + ``socketTimeoutMS`` option set to 5000 milliseconds. +- Operations occur, on average, every 3000 milliseconds, and reconnection + requests are frequent. +- Each socket times out after 5000 milliseconds, which means that all sockets + must do something during those 5000 milliseconds to avoid closing. -One message every 3000 milliseconds is not enough to keep the sockets -active, so several of the sockets will time out after 5000 milliseconds. -To avoid excessive socket timeouts, reduce the number of connections -that the driver can maintain in the connection pool by specifying the -``maxPoolSize`` option. +In this scenario, each socket times out after 5000 milliseconds, requiring +activity within this timeout period to avoid closure. However, one message every +3000 milliseconds isn't enough to keep all sockets active, causing several of +them to time out. -To specify the optional ``maxPoolSize`` setting for your ``MongoClient``, declare -it in the ``options`` object of the constructor as follows: +To avoid excessive socket timeouts, reduce the number of connections that the +driver can maintain in the connection pool by specifying the ``maxPoolSize`` +option. To learn how to set the ``maxPoolSize`` option, see the +:ref:`node-connection-pool-max-pool-size` section. -.. code-block:: javascript +API Documentation +----------------- - const client = new MongoClient(uri, { - maxPoolSize: , - }); \ No newline at end of file +For more information about creating a ``MongoClient`` object with the +{+driver-short+} and specifying options, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ +- `maxPoolSize <{+api+}/interfaces/MongoClientOptions.html#maxPoolSize>`__ +- `maxConnecting <{+api+}/interfaces/MongoClientOptions.html#maxConnecting>`__ +- `minPoolSize <{+api+}/interfaces/MongoClientOptions.html#minPoolSize>`__ +- `maxIdleTimeMS <{+api+}/interfaces/MongoClientOptions.html#maxIdleTimeMS>`__ +- `waitQueueTimeoutMS <{+api+}/interfaces/MongoClientOptions.html#waitQueueTimeoutMS>`__