diff --git a/source/connect.txt b/source/connect.txt index 526a3aae..ad229d04 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -30,6 +30,7 @@ Connect to MongoDB Customize Server Selection Stable API Limit Server Execution Time + Connection Pools Compression Overview diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt new file mode 100644 index 00000000..48ee9ac2 --- /dev/null +++ b/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://:/?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