DOCSP-28558: connection pool faq + reuse client tip (#636)

* DOCSP-28558: connection pool + reuse client

* first pass fixes

* DB PR fixes 1

* small fixes

* fixes

* wording fix

* capitalization

(cherry picked from commit 9343c30)

Author: rustagir

source/faq.txt

@@ -1,17 +1,104 @@
+.. _node-faq:
+
 ===
 FAQ
 ===
 
-.. default-domain:: mongodb
-
-Frequently Asked Questions
-
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 2
+   :depth: 1
    :class: singlecol
 
+This page contains frequently asked questions and their corresponding answers.
+
+.. tip::
+
+   If you can't find an answer to your problem on this page,
+   see the :ref:`node-issues-help` page for next steps and more
+   resources.
+
+.. _node-faq-connection-pool:
+
+How Does Connection Pooling Work in the Node Driver?
+----------------------------------------------------
+
+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 additional 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 <read-preference>` to query the
+secondary nodes, those connection pools grow and there can be
+``306`` total connections.
+
+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 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.
+
+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:
+
+.. code-block:: js
+   
+   const client = new MongoClient("<connection string>");
+
+``MongoClient`` supports multiple concurrent requests. For each process,
+create a client and reuse it for all operations in a process. This
+practice is more efficient than creating a client for each request.
+
+The driver does not limit the number of requests that
+can wait for sockets to become available, and it is the application's
+responsibility to limit the size of its pool to bound queuing
+during a load spike. Requests wait for the amount of time specified in
+the ``waitQueueTimeoutMS`` option, which defaults to ``0`` (no limit).
+
+A request that waits more than the length of time defined by
+``waitQueueTimeoutMS`` for a socket raises a connection error. Use this
+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, so you cannot interrupt or terminate
+any ongoing operations by using this method. The driver closes these
+sockets only when the process completes.
+
 How to fix a "MongoServerSelectionError: connect ECONNREFUSED ::1:27017" error?
 -------------------------------------------------------------------------------
 
@@ -41,7 +128,6 @@ options to resolve this error:
         family: 4,
       });
 
-
 What Is the Difference Between "connectTimeoutMS", "socketTimeoutMS" and "maxTimeMS"?
 -------------------------------------------------------------------------------------
 

source/fundamentals/connection/connect.txt

@@ -64,6 +64,14 @@ You must create a client to connect to a MongoDB deployment on Atlas. To create
 a client, construct an instance of ``MongoClient``, passing in your 
 URI and a ``MongoClientOptions`` object.
 
+.. tip:: Reuse Your Client
+
+   As each ``MongoClient`` represents a pool of connections to the
+   database, most applications only require a single instance of a
+   ``MongoClient``, even across multiple requests. To learn more about
+   how connection pools work in the driver, see the :ref:`FAQ page
+   <node-faq-connection-pool>`.
+
 Use the ``serverApi`` option in your ``MongoClientOptions`` object to
 enable the {+stable-api+} feature, which forces the server to run operations
 with behavior compatible with the specified API version.

source/fundamentals/transactions.txt

@@ -46,7 +46,11 @@ You can use the driver to perform multi-document transactions.
 
 In MongoDB, multi-document transactions run within a **client session**.
 A client session is a grouping of related read or write operations that
-you want to ensure run sequentially. When combined with majority read and
+you want to ensure run sequentially. We recommend you reuse
+your client for multiple sessions and transactions instead of
+instantiating a new client each time.
+
+When combined with majority read and
 write concerns, the driver can guarantee causal consistency between the
 operations. See the server manual guide on
 :manual:`Client Sessions and Causal Consistency Guarantees </core/read-isolation-consistency-recency/#std-label-sessions>`

source/issues-and-help.txt

@@ -1,3 +1,5 @@
+.. _node-issues-help:
+
 =============
 Issues & Help
 =============