@@ -27,4 +27,115 @@ gets a connection from the pool, performs operations, and returns the connection
2727to the pool for reuse.
2828
2929Connection pools help reduce application latency and the number of times new connections
30- are created by {+driver-short+}.
30+ are created by {+driver-short+}.
31+
32+ .. _node-faq-connection-pool:
33+
34+ Connection Pool Overview
35+ -------------------------
36+
37+ Every ``MongoClient`` instance has a built-in connection pool for each server
38+ in your MongoDB topology. Connection pools open sockets on demand to
39+ support concurrent requests to MongoDB in your application.
40+
41+ The maximum size of each connection pool is set by the ``maxPoolSize`` option, which
42+ defaults to ``100``. If the number of in-use connections to a server reaches
43+ the value of ``maxPoolSize``, the next request to that server will wait
44+ until a connection becomes available.
45+
46+ In addition to the sockets needed to support your application's requests,
47+ each ``MongoClient`` instance opens two more sockets per server
48+ in your MongoDB topology for monitoring the server's state.
49+ For example, a client connected to a three-node replica set opens six
50+ monitoring sockets. If the application uses the default setting for
51+ ``maxPoolSize`` and only queries the primary (default) node, then
52+ there can be at most ``106`` total connections in the connection pool. If the
53+ application uses a :ref:`read preference <read-preference>` to query the
54+ secondary nodes, those connection pools grow and there can be
55+ ``306`` total connections.
56+
57+ To support high numbers of concurrent MongoDB requests
58+ within one process, you can increase ``maxPoolSize``.
59+
60+ Connection pools are rate-limited. The ``maxConnecting`` option
61+ determines the number of connections that the pool can create in
62+ parallel at any time. For example, if the value of ``maxConnecting`` is
63+ ``2``, the third request that attempts to concurrently check out a
64+ connection succeeds only when one the following cases occurs:
65+
66+ - The connection pool finishes creating a connection and there are fewer
67+ than ``maxPoolSize`` connections in the pool.
68+ - An existing connection is checked back into the pool.
69+ - The driver's ability to reuse existing connections improves due to
70+ rate-limits on connection creation.
71+
72+ You can set the minimum number of concurrent connections to
73+ each server with the ``minPoolSize`` option, which defaults to ``0``.
74+ The driver initializes the connection pool with this number of sockets. If
75+ sockets are closed, causing the total number
76+ of sockets (both in use and idle) to drop below the minimum, more
77+ sockets are opened until the minimum is reached.
78+
79+ You can set the maximum number of milliseconds that a connection can
80+ remain idle in the pool by setting the ``maxIdleTimeMS`` option.
81+ Once a connection has been idle for ``maxIdleTimeMS``, the connection
82+ pool removes and replaces it. This option defaults to ``0`` (no limit).
83+
84+ The following default configuration for a ``MongoClient`` works for most
85+ applications:
86+
87+ .. code-block:: js
88+
89+ const client = new MongoClient("<connection string>");
90+
91+ ``MongoClient`` supports multiple concurrent requests. For each process,
92+ create a client and reuse it for all operations in a process. This
93+ practice is more efficient than creating a client for each request.
94+
95+ The driver does not limit the number of requests that
96+ can wait for sockets to become available, and it is the application's
97+ responsibility to limit the size of its pool to bound queuing
98+ during a load spike. Requests wait for the amount of time specified in
99+ the ``waitQueueTimeoutMS`` option, which defaults to ``0`` (no limit).
100+
101+ A request that waits more than the length of time defined by
102+ ``waitQueueTimeoutMS`` for a socket raises a connection error. Use this
103+ option if it is more important to bound the duration of operations
104+ during a load spike than it is to complete every operation.
105+
106+ When ``MongoClient.close()`` is called by any request, the driver
107+ closes all idle sockets and closes all sockets that are in
108+ use as they are returned to the pool. Calling ``MongoClient.close()``
109+ closes only inactive sockets and does not directly terminate
110+ any ongoing operations. The driver closes any in-use sockets only when
111+ the associated operations complete. However, the ``MongoClient.close()``
112+ method does close existing sessions and transactions, which might indirectly
113+ affect the behavior of ongoing operations and open cursors.
114+
115+ Avoid Socket Timeouts
116+ ---------------------
117+
118+ Having a large connection pool does not always reduce reconnection
119+ requests. Consider the following example:
120+
121+ An application has a connection pool size of 5 sockets and has the
122+ ``socketTimeoutMS`` option set to 5000 milliseconds. Operations occur,
123+ on average, every 3000 milliseconds, and reconnection requests are
124+ frequent. Each socket times out after 5000 milliseconds, which means
125+ that all sockets must do something during those 5000 milliseconds to
126+ avoid closing.
127+
128+ One message every 3000 milliseconds is not enough to keep the sockets
129+ active, so several of the sockets will time out after 5000 milliseconds.
130+ To avoid excessive socket timeouts, reduce the number of connections
131+ that the driver can maintain in the connection pool by specifying the
132+ ``maxPoolSize`` option.
133+
134+ To specify the optional ``maxPoolSize`` setting for your ``MongoClient``, declare
135+ it in the ``options`` object of the constructor as follows:
136+
137+ .. code-block:: javascript
138+
139+ const client = new MongoClient(uri, {
140+ maxPoolSize: <integer value>,
141+ });
0 commit comments