DOCSP-47709 - move connection pool options (#178) (#181)

Co-authored-by: Rea Rustagi <[email protected]>
(cherry picked from commit ca899d2)

Co-authored-by: Mike Woofter <[email protected]>

Author: github-actions[bot]

config/redirects

@@ -12,3 +12,4 @@ raw: ${prefix}/master -> ${base}/upcoming/
 raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/download-and-install/
 
 [*-master]: ${prefix}/${version}/security/enterprise-authentication/ -> ${base}/${version}/security/authentication/
+[*-master]: ${prefix}/${version}/connect/connection-pools/ -> ${base}/${version}/connect/connection-options/#connection-pools

source/connect.txt

@@ -30,7 +30,6 @@ 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>
 
 Overview
 --------

source/connect/connection-options.txt

@@ -7,7 +7,7 @@ Specify Connection Options
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 .. facet::
@@ -80,7 +80,7 @@ Network Compression
    * - Connection Option
      - Description
 
-   * - **compressors**
+   * - ``compressors``
      - | The preferred compression types, in order, for wire-protocol messages sent to
        | or received from the server. The driver uses the first of these compression types
        | that the server supports.
@@ -90,7 +90,7 @@ Network Compression
        | **MongoClient Example**: ``compressors = "snappy,zstd,zlib"``
        | **Connection URI Example**: ``compressors=snappy,zstd,zlib``
 
-   * - **zlibCompressionLevel**
+   * - ``zlibCompressionLevel``
      - | The compression level for zlib to use. This option accepts
        | an integer value between ``-1`` and ``9``:
        | 
@@ -114,7 +114,7 @@ Timeouts
    * - Connection Option
      - Description
 
-   * - **timeoutMS**
+   * - ``timeoutMS``
      - | The number of milliseconds each driver operation must complete within. If an
        | operation doesn't finish in the specified time, {+driver-short+} raises a timeout exception.
        | For more information, see :ref:`<pymongo-csot>`.
@@ -134,7 +134,7 @@ Server Selection
    * - Connection Option
      - Description
 
-   * - **server_selector**
+   * - ``server_selector``
      - | A user-defined Python function called by {+driver-short+} to choose the server
        | to run an operation against. For more information, see
        | :ref:`<pymongo-server-selection>`.
@@ -144,6 +144,91 @@ Server Selection
        | **MongoClient Example**: ``server_selector = your_function``
        | **Connection URI Example**: N/A
 
+Connection Pools
+~~~~~~~~~~~~~~~~
+
+A **connection pool** is a cache of open database connections maintained by {+driver-short+}.
+When your application requests a connection to MongoDB, {+driver-short+}
+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 that {+driver-short+} must create new connections.
+
+To learn more about connection pools, see
+:manual:`Connection Pool Overview </administration/connection-pool-overview/>`
+in the {+mdb-server+} manual.
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Setting
+     - Description
+
+   * - ``connectTimeoutMS``
+     - | The time that {+driver-short+} waits when connecting a new
+         socket before timing out.
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``20000``
+       | **MongoClient Example**: ``connectTimeoutMS = 40000``
+       | **Connection URI Example**: ``connectTimeoutMS=40000``
+
+   * - ``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**: ``int``
+       | **Default**: ``2``
+       | **MongoClient Example**: ``maxConnecting = 3``
+       | **Connection URI Example**: ``maxConnecting=3``
+
+   * - ``maxIdleTimeMS``
+     - | The maximum time that a connection can remain idle in the pool.
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``None`` (no limit)
+       | **MongoClient Example**: ``maxIdleTimeMS = 60000``
+       | **Connection URI Example**: ``maxIdleTimeMS=60000``
+
+   * - ``maxPoolSize``
+     - | 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**: ``int``
+       | **Default**: ``100``
+       | **MongoClient Example**: ``maxPoolSize = 150``
+       | **Connection URI Example**: ``maxPoolSize=150``
+
+   * - ``minPoolSize``
+     - | 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.
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``0``
+       | **MongoClient Example**: ``minPoolSize = 3``
+       | **Connection URI Example**: ``minPoolSize=3``
+
+   * - ``socketTimeoutMS``
+     - | The length of time that {+driver-short+} waits for a response from the server
+         before timing out.
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``None`` (no timeout)
+       | **MongoClient Example**: ``socketTimeoutMS = 100000``
+       | **Connection URI Example**: ``socketTimeoutMS=100000``
+
+   * - ``waitQueueTimeoutMS``
+     - | How long a thread waits for a connection to become available in the connection pool
+         before timing out.
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``None`` (no timeout)
+       | **MongoClient Example**: ``waitQueueTimeoutMS = 100000``
+       | **Connection URI Example**: ``waitQueueTimeoutMS=100000``
+
 Authentication
 ~~~~~~~~~~~~~~
 
@@ -154,7 +239,7 @@ Authentication
    * - Connection Option
      - Description
 
-   * - **authMechanism**
+   * - ``authMechanism``
      - | The mechanism {+driver-short+} uses to authenticate the application. Valid
        | options are defined in `MECHANISMS. <{+api-root+}pymongo/database.html#pymongo.auth.MECHANISMS>`__
        |
@@ -164,7 +249,7 @@ Authentication
        | **MongoClient Example**: ``authMechanism = "MONGODB-X509"``
        | **Connection URI Example**: ``authMechanism=MONGODB-X509``
 
-   * - **authMechanismProperties**
+   * - ``authMechanismProperties``
      - | Options specific to the authentication mechanism. Not needed for all authentication
        | mechanisms.
        |
@@ -173,15 +258,15 @@ Authentication
        | **MongoClient Example**: ``authMechanismProperties = "AWS_SESSION_TOKEN:12345"``
        | **Connection URI Example**: ``authMechanismProperties=AWS_SESSION_TOKEN:12435``
 
-   * - **authSource**
+   * - ``authSource``
      - | The database to authenticate against.
        |
        | **Data Type**: {+string-data-type+}
        | **Default**: The database in the connection URI, or ``"admin"`` if none is provided
        | **MongoClient Example**: ``authSource = "admin"``
        | **Connection URI Example**: ``authSource=admin``
 
-   * - **username**
+   * - ``username``
      - | The username for authentication. When this option is included in a connection
        | URI, you must percent-escape it.
        |
@@ -190,7 +275,7 @@ Authentication
        | **MongoClient Example**: ``username = "my user"``
        | **Connection URI Example**: ``username=my+user``
 
-   * - **password**
+   * - ``password``
      - | The password for authentication. When this option is included in a connection
        | URI, you must percent-escape it.
        |
@@ -211,39 +296,39 @@ Read and Write Operations
    * - Connection Option
      - Description
 
-   * - **replicaSet**
+   * - ``replicaSet``
      - | Specifies the name of the replica set to connect to.
        |
        | **Data Type**: {+string-data-type+}
        | **Default**: ``null``
        | **MongoClient Example**: ``replicaSet='replicaSetName'``
        | **Connection URI Example**: ``replicaSet=replicaSetName``
 
-   * - **directConnection**
+   * - ``directConnection``
      - | Whether to connect only to the primary member of the replica set.
        |
        | **Data Type**: {+bool-data-type+}
        | **Default**: ``False``
        | **MongoClient Example**: ``directConnection=True``
        | **Connection URI Example**: ``directConnection=true``
 
-   * - **readPreference**
+   * - ``readPreference``
      - | Specifies the client's read-preference settings.
        |
        | **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__
        | **Default**: ``ReadPreference.Primary``
        | **MongoClient Example**: ``readPreference=ReadPreference.SECONDARY_PREFERRED``
        | **Connection URI Example**: ``readPreference=secondaryPreferred``
 
-   * - **readConcern**
+   * - ``readConcern``
      - | Specifies the client's read-concern settings. For more information, see :manual:`</reference/read-concern/>`.
        |
        | **Data Type**: {+string-data-type+}
        | **Default**: ``None``
        | **MongoClient Example**: ``readConcern="majority"``
        | **Connection URI Example**: ``readConcern=majority``
 
-   * - **writeConcern**
+   * - ``writeConcern``
      - | Specifies the client's write-concern settings. For more information, see
          :manual:`</reference/write-concern/>`.
        |
@@ -252,7 +337,7 @@ Read and Write Operations
        | **MongoClient Example**: ``writeConcern="majority"``
        | **Connection URI Example**: ``writeConcern=majority``
 
-   * - **localThresholdMS**
+   * - ``localThresholdMS``
      - | The latency window for a replica-set members eligibility. If a member's
          round trip ping takes longer than the fastest server's round-trip ping
          time plus this value, the server isn't eligible for selection.
@@ -262,7 +347,7 @@ Read and Write Operations
        | **MongoClient Example**: ``localThresholdMS=35``
        | **Connection URI Example**: ``localThresholdMS=35``
 
-   * - **retryReads**
+   * - ``retryReads``
      - | Specifies whether the client retries supported read operations. For more
          information, see :manual:`Retryable Reads </core/retryable-reads/>` in the {+mdb-server+}
          manual.
@@ -272,7 +357,7 @@ Read and Write Operations
        | **MongoClient Example**: ``retryReads=False``
        | **Connection URI Example**: ``retryReads=false``
 
-   * - **retryWrites**
+   * - ``retryWrites``
      - | Specifies whether the client retries supported write operations. For more
          information, see :manual:`Retryable Writes </core/retryable-writes/>` in the {+mdb-server+}
          manual.