DOCSP-49058: Connection Pools

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

@@ -1,86 +1,148 @@
-.. TODO: Connection Pools page
-
 .. _csharp-faq-connection-pool:
 .. _csharp-connection-pools:
 
-How Does Connection Pooling Work in the {+driver-short+}?
----------------------------------------------------------
+================
+Connection Pools
+================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
 
-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 MongoDB operations in your multi-threaded application.
+Overview
+--------
 
-The maximum size of each connection pool is set by the ``MaxConnectionPoolSize`` option, which
-defaults to ``100``. If the number of in-use connections to a server reaches
-the value of ``MaxConnectionPoolSize``, the next request to that server will wait
-until a connection becomes available. The following diagram illustrates a high-level view
+In this guide, you can learn about how the {+driver-short+} uses connection pools to manage
+connections to a MongoDB deployment and how you can configure connection pool settings
+in your application.
+
+A connection pool is a cache of open database connections maintained by the {+driver-short+}.
+When your application requests a connection to MongoDB, the {+driver-short+} seamlessly
+gets a connection from the pool, performs operations, and returns the connection
+to the pool for reuse.
+
+Connection pools help reduce application latency and the number of times new connections
+are created by the {+driver-short+}. The following diagram illustrates a high-level view
 of how the ``MongoClient`` manages a connection pool:
 
 .. figure:: /includes/figures/CMAP_diagram.svg
    :alt: CMAP diagram
 
-In addition to the sockets needed to support your application's threads,
-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
-``MaxConnectionPoolSize`` and only queries the primary (default) node, then
-there can be at most ``106`` total connections in use. 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 threads
-within one process, you can increase ``MaxConnectionPoolSize``.
-
-The driver has a wait queue that limits the number of threads that can
-wait for a connection. The size of the wait queue is determined by the
-``WaitQueueMultiple`` option, which defaults to ``5``. To calculate the
-maximum wait queue size, the driver multiplies ``WaitQueueMultiple`` by
-``MaxConnectionPoolSize``. If you use the default value for each option,
-the wait queue size will be ``500``. You can also set the wait queue
-size by specifying the ``WaitQueueSize`` option, which overrides the
-other settings. However, we do not recommend changing the wait queue
-size from the default.
-
-Connection pools are rate-limited. The ``MaxConnecting`` setting
-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 thread that attempts to concurrently check out a
-connection succeeds only in one of the following cases:
-
-- One of the first two threads finishes creating a connection.
-- 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 by using the ``MinConnectionPoolSize`` option, which
-defaults to ``0``. The connection pool will be initialized with this
-number of sockets. If errors cause any sockets to close and the
-total number of sockets (both in-use and idle) drops below the minimum,
-the driver opens more sockets until the number reaches the minimum.
-
-You can set the maximum number of milliseconds that a connection can
-remain idle in the pool by using the ``MaxConnectionIdleTime`` option.
-Once a connection is idle for ``MaxConnectionIdleTime``, the driver
-removes it. This option defaults to 10 minutes. If the pool size falls
-below ``MinConnectionPoolSize``, the driver removes *and* replaces the
-idle connection.
-
-``MongoClient`` also has the ``MaxConnectionLifeTime`` option, which
-specifies the length of time, 30 minutes by default, that a connection
-can be pooled before expiring.
-
-The following default configuration for a ``MongoClient`` works for most
-applications:
+Configuring Connection Pools
+----------------------------
+
+You can specify the following connection pool settings in your ``MongoClient`` object or in
+your connection URI:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Setting
+     - Description
+
+   * - ``ConnectTimeout``
+     - | The time that the {+driver-short+} waits when establishing a new
+         connection before timing out.
+       |
+       | **Data Type**: ``TimeSpan``
+       | **Default**: 30 seconds
+       | **Connection URI Example**: ``connectTimeoutMS=0``
+
+   * - ``MaxConnecting``
+     - | The maximum number of connections that each pool can establish concurrently.
+         If this limit is reached, further requests wait until a connection is established
+         or another in-use connection is checked back into the pool.
+       |
+       | **Data Type**: ``integer``
+       | **Default**: ``2``
+       | **Connection URI Example**: ``maxConnecting=3``
+
+   * - ``MaxConnectionIdleTime``
+     - | The maximum time that a connection can remain idle in the pool. When a connection
+         exceeds this limit, the {+driver-short+} closes the connection and removes it from
+         the pool.
+       |
+       | **Data Type**: ``TimeSpan``
+       | **Default**: 10 minutes
+       | **Connection URI Example**: ``maxIdleTimeMS=60000``
+
+   * - ``MaxConnectionLifeTime``
+     - | The maximum time that a connection can be pooled. When a connection exceeds this
+         limit, the {+driver-short+} closes the connection and removes it from the pool.
+       |
+       | **Data Type**: ``TimeSpan``
+       | **Default**: 30 minutes
+       | **Connection URI Example**: ``maxLifeTimeMS=50000``
+
+   * - ``MaxConnectionPoolSize``
+     - | The maximum number of concurrent connections that the pool maintains.
+         If the maximum pool size is reached, further requests wait until a connection
+         becomes available.
+       |
+       | **Data Type**: ``integer``
+       | **Default**: ``100``
+       | **Connection URI Example**: ``maxPoolSize=150``
+
+   * - ``MinConnectionPoolSize``
+     - | The minimum number of concurrent connections that the pool maintains. If
+         the number of open connections falls below this value due to network errors,
+         the {+driver-short+} attempts to create new connections to maintain this minimum.
+       |
+       | **Data Type**: ``integer``
+       | **Default**: ``0``
+       | **Connection URI Example**: ``minPoolSize=3``
+
+   * - ``SocketTimeout``
+     - | The length of time that the {+driver-short+} waits for a response from the server
+         before timing out.
+       |
+       | **Data Type**: ``TimeSpan``
+       | **Default**: OS default
+       | **Connection URI Example**: ``socketTimeoutMS=100000``
+
+   * - ``WaitQueueTimeout``
+     - | How long a thread waits for a connection to become available in the connection pool
+         before timing out.
+       |
+       | **Data Type**: ``TimeSpan``
+       | **Default**: 2 minutes
+       | **Connection URI Example**: ``waitQueueTimeoutMS=100000``
+
+The following code creates a client with a maximum connection pool size of ``50`` by using the
+``MaxConnectionPoolSize`` parameter:
+
+.. code-block:: csharp
+
+   var settings = MongoClientSettings.FromConnectionString("<connection URI>");
+   settings.MaxConnectionPoolSize = 50;
+   var client = new MongoClient(settings);
+
+The following code creates a client with the same configuration as the preceding example,
+but uses a connection URI:
 
 .. code-block:: csharp
 
-   var client = new MongoClient("<connection string>");
+   var settings = MongoClientSettings.FromConnectionString("<hostname>?maxPoolSize=50");
+   var client = new MongoClient(settings);
+
+Additional Information
+----------------------
+
+To learn more about connection pools, see :manual:`Connection Pool Overview </administration/connection-pool-overview/>`
+in the {+mdb-server+} manual.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
 
-Create a client once for each process, and reuse it for all
-operations. It is a common mistake to create a new client for each
-request, which is very inefficient.
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
 
-There is no supported way to terminate a ``MongoClient`` in the driver.
+- `MongoClient <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClient.html>`__
+- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__