From 6a81374524c400c4d04ee82b80e5a452297850b9 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 1 Apr 2025 13:36:08 -0700 Subject: [PATCH 1/7] cleanup faq content --- .../connection-options/connection-pools.txt | 172 ++++++++++++++---- 1 file changed, 137 insertions(+), 35 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 97fa3533a..1ab8fcd87 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -31,21 +31,59 @@ are created by {+driver-short+}. .. _node-faq-connection-pool: -Connection Pool Overview -------------------------- +Configuring Connection Pools +---------------------------- 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. +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) + +maxPoolSize +~~~~~~~~~~~ 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 @@ -57,6 +95,21 @@ secondary nodes, those connection pools grow and there can be To support high numbers of concurrent MongoDB requests within one process, you can increase ``maxPoolSize``. +The following code creates a ``MongoClient`` instance with a maximum connection +pool size of ``50`` by using the ``maxPoolSize`` option: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxPoolSize: 50 + }); + +maxConnecting +~~~~~~~~~~~~~ + 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 @@ -69,24 +122,63 @@ connection succeeds only when one the following cases occurs: - 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 +connection that the pool can create set to ``2``: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxConnecting: 2 + }); + +minPoolSize +~~~~~~~~~~~ + +You can set the minimum number of concurrent connections to each server with the +``minPoolSize`` option. 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 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 + }); + +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:: js - - const client = new MongoClient(""); +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxIdleTimeMS: 10000 + }); + +waitQueueTimeoutMS +~~~~~~~~~~~~~~~~~~ ``MongoClient`` supports multiple concurrent requests. For each process, create a client and reuse it for all operations in a process. This @@ -103,6 +195,22 @@ 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. +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 + }); + +Clossing Connections +-------------------- + 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()`` @@ -116,26 +224,20 @@ 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. + +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. -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. - -To specify the optional ``maxPoolSize`` setting for your ``MongoClient``, declare -it in the ``options`` object of the constructor as follows: - -.. code-block:: javascript - - const client = new MongoClient(uri, { - maxPoolSize: , - }); \ No newline at end of file From f68c492274df75a14f598ae13c1e658b89fc09f5 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 2 Apr 2025 10:17:15 -0700 Subject: [PATCH 2/7] edits --- .../connection-options/connection-pools.txt | 48 +++++++++++++------ 1 file changed, 34 insertions(+), 14 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 1ab8fcd87..fd4feba05 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -77,6 +77,9 @@ instance: | | **Default**: ``0`` (no limit) + +.. _node-connection-pool-max-pool-size: + maxPoolSize ~~~~~~~~~~~ @@ -107,6 +110,8 @@ pool size of ``50`` by using the ``maxPoolSize`` option: maxPoolSize: 50 }); +.. _node-connection-pool-max-connecting: + maxConnecting ~~~~~~~~~~~~~ @@ -134,6 +139,8 @@ connection that the pool can create set to ``2``: maxConnecting: 2 }); +.. _node-connection-pool-min-pool-size: + minPoolSize ~~~~~~~~~~~ @@ -156,6 +163,8 @@ object: minPoolSize: 10 }); +.. _node-connection-pool-max-idle-time: + maxIdleTimeMS ~~~~~~~~~~~~~ @@ -177,6 +186,8 @@ setting in the ``options`` object: maxIdleTimeMS: 10000 }); +.. _node-connection-pool-wait-queue-timeout: + waitQueueTimeoutMS ~~~~~~~~~~~~~~~~~~ @@ -208,17 +219,25 @@ timeout of ``10000`` milliseconds (10 seconds) by declaring it in the waitQueueTimeoutMS: 10000 }); -Clossing Connections +Closing Connections -------------------- -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. +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 --------------------- @@ -230,14 +249,15 @@ requests. Consider the following example scenario: ``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. +- Each socket times out after 5000 milliseconds, which means that all sockets + must do something during those 5000 milliseconds to avoid closing. 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 avoid excessive socket timeouts, reduce the number of connections -that the driver can maintain in the connection pool by specifying the -``maxPoolSize`` option. +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 this option, see +:ref:`node-connection-pool-max-pool-size`. From 6a76b520c0fa73cc2a8b5a36f5fab229af3985ae Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 2 Apr 2025 10:34:39 -0700 Subject: [PATCH 3/7] add resources --- .../connection-options/connection-pools.txt | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index fd4feba05..3fd0bdc27 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -99,7 +99,8 @@ To support high numbers of concurrent MongoDB requests within one process, you can increase ``maxPoolSize``. The following code creates a ``MongoClient`` instance with a maximum connection -pool size of ``50`` by using the ``maxPoolSize`` option: +pool size of ``50`` by specifying the ``maxPoolSize`` option in the +``options`` object: .. code-block:: javascript @@ -128,7 +129,8 @@ connection succeeds only when one the following cases occurs: rate-limits on connection creation. The following code creates a ``MongoClient`` instance with a maximum number of -connection that the pool can create set to ``2``: +``2`` connections by specifying the ``maxConnecting`` option in the ``options`` +object: .. code-block:: javascript @@ -259,5 +261,14 @@ them to time out. 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 this option, see -:ref:`node-connection-pool-max-pool-size`. +option. To learn how to set this option, see the +:ref:`node-connection-pool-max-pool-size` section. + +API Documentation +----------------- + +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>`__ From 6a22c7e58b8b48c11dbb24d9c3bab51da60d1535 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 2 Apr 2025 15:52:15 -0700 Subject: [PATCH 4/7] lm feedback --- .../connection-options/connection-pools.txt | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 3fd0bdc27..60c576f04 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 Using Connection Pools +========================================= .. facet:: :name: genre @@ -31,8 +31,8 @@ are created by {+driver-short+}. .. _node-faq-connection-pool: -Configuring Connection Pools ----------------------------- +Configure Connection Pools +-------------------------- Every ``MongoClient`` instance has a built-in connection pool for each server in your MongoDB topology. Connection pools open sockets on demand to @@ -147,10 +147,10 @@ minPoolSize ~~~~~~~~~~~ You can set the minimum number of concurrent connections to each server with the -``minPoolSize`` option. 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. +``minPoolSize`` option. The driver initializes the connection pool with the +number of sockets set by the option. 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`` @@ -261,7 +261,7 @@ them to time out. 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 this option, see the +option. To learn how to set the ``maxPoolSize`` option, see the :ref:`node-connection-pool-max-pool-size` section. API Documentation @@ -272,3 +272,8 @@ For more information about creating a ``MongoClient`` object with the - `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>`__ From be8102854e2f6ea01fb10208a6d03b97a1da64b4 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 3 Apr 2025 09:03:59 -0700 Subject: [PATCH 5/7] update title --- source/connect/connection-options/connection-pools.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 60c576f04..3ec1226e1 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -1,8 +1,8 @@ .. _node-connection-pools: -========================================= -Manage Connections Using Connection Pools -========================================= +======================================== +Manage Connections with Connection Pools +======================================== .. facet:: :name: genre From 653b3872e05d33780232e411681d77e039798e6e Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 3 Apr 2025 10:33:59 -0700 Subject: [PATCH 6/7] tech feedback --- .../connection-options/connection-pools.txt | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 3ec1226e1..5a005af38 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -34,9 +34,10 @@ are created by {+driver-short+}. Configure Connection Pools -------------------------- -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. +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: @@ -83,23 +84,23 @@ instance: maxPoolSize ~~~~~~~~~~~ -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. +In addition to the sockets needed to support your application's requests, each +``MongoClient`` instance opens up to two or more 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`` 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. +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``. The following code creates a ``MongoClient`` instance with a maximum connection -pool size of ``50`` by specifying the ``maxPoolSize`` option in the +pool size of ``200`` by specifying the ``maxPoolSize`` option in the ``options`` object: .. code-block:: javascript @@ -108,7 +109,7 @@ pool size of ``50`` by specifying the ``maxPoolSize`` option in the const uri = ''; const client = new MongoClient(uri, { - maxPoolSize: 50 + maxPoolSize: 200 }); .. _node-connection-pool-max-connecting: @@ -116,21 +117,19 @@ pool size of ``50`` by specifying the ``maxPoolSize`` option in the maxConnecting ~~~~~~~~~~~~~ -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: +Connection pools rate-limit of 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. The following code creates a ``MongoClient`` instance with a maximum number of -``2`` connections by specifying the ``maxConnecting`` option in the ``options`` -object: +``2`` connections to be established concurrently per pool by specifying the +``maxConnecting`` option in the ``options`` object: .. code-block:: javascript @@ -146,11 +145,12 @@ object: minPoolSize ~~~~~~~~~~~ -You can set the minimum number of concurrent connections to each server with the -``minPoolSize`` option. The driver initializes the connection pool with the -number of sockets set by the option. 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. +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`` From ce4ad602e6858759f07555b2a79d76af79d0f288 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 10 Apr 2025 14:26:29 -0700 Subject: [PATCH 7/7] bp feedback --- source/connect/connection-options/connection-pools.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 5a005af38..f70abd878 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -85,7 +85,7 @@ maxPoolSize ~~~~~~~~~~~ In addition to the sockets needed to support your application's requests, each -``MongoClient`` instance opens up to two or more connections per server in your +``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 @@ -117,7 +117,7 @@ pool size of ``200`` by specifying the ``maxPoolSize`` option in the maxConnecting ~~~~~~~~~~~~~ -Connection pools rate-limit of connection establishment. The ``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