Skip to content

Commit 63c24f3

Browse files
authored
DOCSP-48388 break up faq (#1048)
* break up faq * vale errors * fix vale error * wording * add redirect * remove faq * change headlines * js feedback * bp edits * bp feedback
1 parent 4992d60 commit 63c24f3

File tree

6 files changed

+363
-396
lines changed

6 files changed

+363
-396
lines changed

config/redirects

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ raw: ${prefix}/stable -> ${base}/current/
1010
[*-master]: ${prefix}/${version}/fundamentals/versioned-api/ -> ${base}/${version}/fundamentals/stable-api/
1111
[*-master]: ${prefix}/${version}/fundamentals/connection/lambda/ -> ${base}/${version}/fundamentals/connection/
1212
[*-master]: ${prefix}/${version}/fundamentals/csfle -> ${base}/${version}/fundamentals/encrypt-fields/
13+
[*-master]: ${prefix}/${version}/faq/ -> ${base}/${version}/
1314

1415
[*-v5.0]: ${prefix}/${version}/quick-start/connect-to-mongodb/ -> ${base}/${version}/quick-start/
1516
[*-v5.0]: ${prefix}/${version}/quick-start/create-a-connection-string/ -> ${base}/${version}/quick-start/

source/connect/connection-options.txt

Lines changed: 113 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,9 @@ string, see :manual:`Connection Strings </reference/connection-string/>` in the
9191
* - **connectTimeoutMS**
9292
- non-negative integer
9393
- ``30000``
94-
- Specifies the amount of time, in milliseconds, to wait to establish a single TCP
94+
- Specifies the amount of time in milliseconds to wait to establish a single TCP
9595
socket connection to the server before raising an error. Specifying
96-
``0`` disables the connection timeout.
96+
``0`` means your application sets an infinite socket timeout when establishing a socket.
9797

9898
* - **directConnection**
9999
- boolean
@@ -255,8 +255,9 @@ string, see :manual:`Connection Strings </reference/connection-string/>` in the
255255
* - **socketTimeoutMS**
256256
- non-negative integer
257257
- ``0``
258-
- Specifies the amount of time, in milliseconds, spent attempting to send or receive on a
259-
socket before timing out. Specifying ``0`` means no timeout.
258+
- Specifies the amount of time in milliseconds spent attempting to send or receive
259+
on a socket before timing out. Specifying ``0`` means your application sets an
260+
infinite socket timeout when establishing a socket.
260261

261262
* - **srvMaxHosts**
262263
- non-negative integer
@@ -343,6 +344,114 @@ string, see :manual:`Connection Strings </reference/connection-string/>` in the
343344
no compression, ``1`` signifies the fastest speed, and ``9`` signifies
344345
the best compression. See :ref:`node-network-compression` for more information.
345346

347+
Connection Time Out Options
348+
---------------------------
349+
350+
.. list-table::
351+
:widths: 22 78
352+
:header-rows: 1
353+
354+
* - Setting
355+
- Description
356+
357+
* - **connectTimeoutMS**
358+
- ``connectTimeoutMS`` is a :ref:`connection option
359+
<node-connection-options>` that sets the time, in milliseconds,
360+
for an individual connection from your connection pool to
361+
establish a TCP connection to the {+mdb-server+} before
362+
timing out. To modify the allowed time for
363+
`MongoClient.connect <{+api+}/classes/MongoClient.html#connect>`__ to establish a
364+
connection to a {+mdb-server+}, use the ``serverSelectionTimeoutMS`` option instead.
365+
366+
**Default:** 30000
367+
368+
* - **socketTimeoutMS**
369+
- ``socketTimeoutMS`` specifies the amount of time the driver waits
370+
for an inactive socket before closing it. The default value is to
371+
never time out the socket. This option applies only to sockets that
372+
have already been connected.
373+
374+
* - **maxTimeMS**
375+
- `maxTimeMS <{+api+}/classes/FindCursor.html#maxTimeMS>`__
376+
specifies the maximum amount of time that the server
377+
waits for an operation to complete after it has reached the
378+
server. If an operation runs over the specified time limit, it
379+
returns a timeout error. You can pass ``maxTimeMS`` only to an
380+
individual operation or to a cursor.
381+
382+
To specify the optional settings for your ``MongoClient``, declare one or
383+
more available settings in the ``options`` object of the constructor as
384+
follows:
385+
386+
.. code-block:: javascript
387+
388+
const client = new MongoClient(uri, {
389+
connectTimeoutMS: <integer value>,
390+
socketTimeoutMS: <integer value>
391+
});
392+
393+
To see all the available settings, see the
394+
`MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__
395+
API Documentation.
396+
397+
To specify ``maxTimeMS``, pass in the ``maxTimeMS`` method as an option with a timeout
398+
specification to an operation that returns a ``Cursor``:
399+
400+
.. code-block:: javascript
401+
402+
const Cursor = collection.distinct('my-key', { maxTimeMS: 50 });
403+
404+
Close Sockets After Connection
405+
------------------------------
406+
407+
If you experience unexpected network behavior or if a MongoDB process
408+
fails with an error, you might not receive confirmation that the
409+
driver correctly closed the corresponding socket.
410+
411+
To make sure that the driver correctly closes the socket in these cases,
412+
set the ``socketTimeoutMS`` option. When a MongoDB process times out, the driver
413+
will close the socket. We recommend that you select a value
414+
for ``socketTimeoutMS`` that is two to three times longer than the
415+
expected duration of the slowest operation that your application executes.
416+
417+
Prevent Long-Running Operations From Slowing Down the Server
418+
------------------------------------------------------------
419+
420+
You can prevent long-running operations from slowing down the server by
421+
specifying a timeout value. You can chain the ``maxTimeMS()`` method to
422+
an operation that returns a ``Cursor`` to set a timeout on a specific action.
423+
424+
The following example shows how you can chain the ``maxTimeMS()`` method
425+
to an operation that returns a ``Cursor``:
426+
427+
.. literalinclude:: /code-snippets/faq/maxTimeMS-example.js
428+
:language: javascript
429+
430+
.. _node-faq-keepalive:
431+
432+
keepAlive Connection Option
433+
---------------------------
434+
435+
The ``keepAlive`` connection option specifies whether to enable
436+
:wikipedia:`Transmission Control Protocol (TCP) keepalives
437+
<Keepalive#TCP_keepalive>` on a TCP socket. If you enable keepalives,
438+
the driver checks whether the connection is active by sending periodic pings
439+
to your MongoDB deployment. This functionality works only if your
440+
operating system supports the ``SO_KEEPALIVE`` socket option.
441+
442+
The ``keepAliveInitialDelay`` option specifies the number of
443+
milliseconds that the driver waits before initiating a keepalive.
444+
445+
The 5.3 driver version release deprecated these options. Starting in
446+
version 6.0 of the driver, the ``keepAlive`` option is permanently set
447+
to ``true``, and the ``keepAliveInitialDelay`` is set to 300000
448+
milliseconds (300 seconds).
449+
450+
.. warning::
451+
452+
If your firewall ignores or drops the keepalive messages, you might
453+
not be able to identify dropped connections.
454+
346455
Additional Information
347456
----------------------
348457

source/connect/connection-options/connection-pools.txt

Lines changed: 112 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,115 @@ gets a connection from the pool, performs operations, and returns the connection
2727
to the pool for reuse.
2828

2929
Connection 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

Comments
 (0)