DOCSP-46691: Connection Pools (#157)

(cherry picked from commit 7634320)

Author: mcmorisi

source/connect.txt

@@ -30,6 +30,7 @@ Connect to MongoDB
    Customize Server Selection </connect/server-selection>
    Stable API </connect/stable-api>
    Limit Server Execution Time </connect/csot>
+   Connection Pools </connect/connection-pools>
    Compression </connect/compression>
 
 Overview

source/connect/connection-pools.txt

@@ -0,0 +1,108 @@
+.. _pymongo-connection-pools:
+
+================
+Connection Pools
+================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn about how {+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 {+driver-short+}.
+When your application requests a connection to MongoDB, {+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 {+driver-short+}.
+
+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
+
+   * - ``connectTimeoutMS``
+     - | Sets the time that {+driver-short+} waits when connecting a new
+         socket before timing out.
+       | Defaults to ``20000``
+
+   * - ``maxConnecting``
+     - | Sets 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.
+       | Defaults to ``2``
+
+   * - ``maxIdleTimeMS``
+     - | Sets the maximum time that a connection can remain idle in the pool.
+       | Defaults to ``None`` (no limit)
+
+   * - ``maxPoolSize``
+     - | Sets 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.
+       | Defaults to ``100``
+
+   * - ``minPoolSize``
+     - | Sets the minimum number of concurrent connections that the pool maintains. If
+         the number of open connections falls below this value due to network errors,
+         {+driver-short+} attempts to create new connections to maintain this minimum.
+       | Defaults to ``0``
+
+   * - ``socketTimeoutMS``
+     - | Sets the length of time that {+driver-short+} waits for a response from the server
+         before timing out.
+       | Defaults to ``None`` (no timeout)
+
+   * - ``waitQueueTimeoutMS``
+     - | Sets how long a thread waits for a connection to become available in the connection pool
+         before timing out.
+       | Defaults to ``None`` (no timeout)
+
+The following code creates a client with a maximum connection pool size of ``50`` by using the
+``maxPoolSize`` parameter:
+
+.. code-block:: python
+
+   client = MongoClient(host, port, maxPoolSize=50)
+
+The following code creates a client with the same configuration as the preceding example,
+but uses a connection URI:
+
+.. code-block:: python
+
+   client = MongoClient("mongodb://<host>:<port>/?maxPoolSize=50")
+
+Additional Information
+----------------------
+
+To learn more about connection pools, see :manual:`Connection Pool Overview </administration/connection-pool-overview/>`
+in the {+mdb-server+} manual.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__