diff --git a/config/redirects b/config/redirects index 24adc3fe..c3e8b7e9 100644 --- a/config/redirects +++ b/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 \ No newline at end of file diff --git a/source/connect.txt b/source/connect.txt index e140716f..6c983b01 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -30,7 +30,6 @@ Connect to MongoDB Customize Server Selection Stable API Limit Server Execution Time - Connection Pools Overview -------- diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 7a872ee0..7d9fe378 100644 --- a/source/connect/connection-options.txt +++ b/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:``. @@ -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:``. @@ -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 ` +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,7 +258,7 @@ 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+} @@ -181,7 +266,7 @@ Authentication | **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,7 +296,7 @@ Read and Write Operations * - Connection Option - Description - * - **replicaSet** + * - ``replicaSet`` - | Specifies the name of the replica set to connect to. | | **Data Type**: {+string-data-type+} @@ -219,7 +304,7 @@ Read and Write Operations | **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+} @@ -227,7 +312,7 @@ Read and Write Operations | **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>`__ @@ -235,7 +320,7 @@ Read and Write Operations | **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:``. | | **Data Type**: {+string-data-type+} @@ -243,7 +328,7 @@ Read and Write Operations | **MongoClient Example**: ``readConcern="majority"`` | **Connection URI Example**: ``readConcern=majority`` - * - **writeConcern** + * - ``writeConcern`` - | Specifies the client's write-concern settings. For more information, see :manual:``. | @@ -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 ` 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 ` in the {+mdb-server+} manual. diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt deleted file mode 100644 index 48ee9ac2..00000000 --- a/source/connect/connection-pools.txt +++ /dev/null @@ -1,108 +0,0 @@ -.. _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://:/?maxPoolSize=50") - -Additional Information ----------------------- - -To learn more about connection pools, see :manual:`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>`__ \ No newline at end of file