options

Author: mongoKart

source/connect/connection-options.txt

@@ -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>`.
@@ -147,6 +147,16 @@ Server Selection
 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+} 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+}.
+
+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
@@ -155,55 +165,70 @@ Connection Pools
      - Description
 
    * - ``connectTimeoutMS``
-     - | Sets the time that {+driver-short+} waits when connecting a new
+     - | The time that {+driver-short+} waits when connecting a new
          socket before timing out.
-       | Defaults to ``20000``
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``20000``
+       | **MongoClient Example**: ``connectTimeoutMS = 40000``
+       | **Connection URI Example**: ``connectTimeoutMS=40000``
 
    * - ``maxConnecting``
-     - | Sets the maximum number of connections that each pool can establish concurrently.
+     - | 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``
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``2``
+       | **MongoClient Example**: ``maxConnecting = 3``
+       | **Connection URI Example**: ``maxConnecting=3``
 
    * - ``maxIdleTimeMS``
-     - | Sets the maximum time that a connection can remain idle in the pool.
-       | Defaults to ``None`` (no limit)
+     - | 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``
-     - | Sets the maximum number of concurrent connections that the pool maintains.
+     - | 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``
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``100``
+       | **MongoClient Example**: ``maxPoolSize = 150``
+       | **Connection URI Example**: ``maxPoolSize=150``
 
    * - ``minPoolSize``
-     - | Sets the minimum number of concurrent connections that the pool maintains. If
+     - | 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``
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``0``
+       | **MongoClient Example**: ``minPoolSize = 3``
+       | **Connection URI Example**: ``minPoolSize=3``
 
    * - ``socketTimeoutMS``
-     - | Sets the length of time that {+driver-short+} waits for a response from the server
+     - | The length of time that {+driver-short+} waits for a response from the server
          before timing out.
-       | Defaults to ``None`` (no timeout)
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``None`` (no timeout)
+       | **MongoClient Example**: ``socketTimeoutMS = 100000``
+       | **Connection URI Example**: ``socketTimeoutMS=100000``
 
    * - ``waitQueueTimeoutMS``
-     - | Sets how long a thread waits for a connection to become available in the connection pool
+     - | 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
+       |
+       | **Data Type**: ``int``
+       | **Default**: ``None`` (no timeout)
+       | **MongoClient Example**: ``waitQueueTimeoutMS = 100000``
+       | **Connection URI Example**: ``waitQueueTimeoutMS=100000``
 
-   client = MongoClient("mongodb://<host>:<port>/?maxPoolSize=50")
 Authentication
 ~~~~~~~~~~~~~~
 
@@ -214,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>`__
        |
@@ -224,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.
        |
@@ -233,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.
        |
@@ -250,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.
        |
@@ -271,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/>`.
        |
@@ -312,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.
@@ -322,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.
@@ -332,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.