diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index db9a3a7e..e2d7d3d0 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -1,86 +1,151 @@ -.. TODO: Connection Pools page - .. _csharp-faq-connection-pool: .. _csharp-connection-pools: -How Does Connection Pooling Work in the {+driver-short+}? ---------------------------------------------------------- +================ +Connection Pools +================ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection, client, latency + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol -Every ``MongoClient`` instance has a built-in connection pool for each server -in your MongoDB topology. Connection pools open sockets on demand to -support concurrent MongoDB operations in your multi-threaded application. +Overview +-------- -The maximum size of each connection pool is set by the ``MaxConnectionPoolSize`` option, which -defaults to ``100``. If the number of in-use connections to a server reaches -the value of ``MaxConnectionPoolSize``, the next request to that server will wait -until a connection becomes available. The following diagram illustrates a high-level view +In this guide, you can learn about how the {+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 the {+driver-short+}. +When your application requests a connection to MongoDB, the {+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 the {+driver-short+}. The following diagram illustrates a high-level view of how the ``MongoClient`` manages a connection pool: .. figure:: /includes/figures/CMAP_diagram.svg :alt: CMAP diagram -In addition to the sockets needed to support your application's threads, -each ``MongoClient`` instance opens two additional sockets per server -in your MongoDB topology for monitoring the server's state. -For example, a client connected to a three-node replica set opens six -monitoring sockets. If the application uses the default setting for -``MaxConnectionPoolSize`` and only queries the primary (default) node, then -there can be at most ``106`` total connections in use. If the -application uses a :ref:`read preference ` to query the -secondary nodes, those connection pools grow and there can be -``306`` total connections. - -To support high numbers of concurrent MongoDB threads -within one process, you can increase ``MaxConnectionPoolSize``. - -The driver has a wait queue that limits the number of threads that can -wait for a connection. The size of the wait queue is determined by the -``WaitQueueMultiple`` option, which defaults to ``5``. To calculate the -maximum wait queue size, the driver multiplies ``WaitQueueMultiple`` by -``MaxConnectionPoolSize``. If you use the default value for each option, -the wait queue size will be ``500``. You can also set the wait queue -size by specifying the ``WaitQueueSize`` option, which overrides the -other settings. However, we do not recommend changing the wait queue -size from the default. - -Connection pools are rate-limited. The ``MaxConnecting`` setting -determines the number of connections that the pool can create in -parallel at any time. For example, if the value of ``MaxConnecting`` is -``2``, the third thread that attempts to concurrently check out a -connection succeeds only in one of the following cases: - -- One of the first two threads finishes creating a connection. -- An existing connection is checked back into the pool. -- The driver's ability to reuse existing connections improves due to - rate-limits on connection creation. - -You can set the minimum number of concurrent connections to -each server by using the ``MinConnectionPoolSize`` option, which -defaults to ``0``. The connection pool will be initialized with this -number of sockets. If errors cause any sockets to close and the -total number of sockets (both in-use and idle) drops below the minimum, -the driver opens more sockets until the number reaches the minimum. - -You can set the maximum number of milliseconds that a connection can -remain idle in the pool by using the ``MaxConnectionIdleTime`` option. -Once a connection is idle for ``MaxConnectionIdleTime``, the driver -removes it. This option defaults to 10 minutes. If the pool size falls -below ``MinConnectionPoolSize``, the driver removes *and* replaces the -idle connection. - -``MongoClient`` also has the ``MaxConnectionLifeTime`` option, which -specifies the length of time, 30 minutes by default, that a connection -can be pooled before expiring. - -The following default configuration for a ``MongoClient`` works for most -applications: +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 + + * - ``ConnectTimeout`` + - | The maximum amount of time that the {+driver-short+} waits when establishing a new + connection before timing out. + | + | **Data Type**: ``TimeSpan`` + | **Default**: 30 seconds + | **Connection URI Example**: ``connectTimeoutMS=0`` + + * - ``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**: ``integer`` + | **Default**: ``2`` + | **Connection URI Example**: ``maxConnecting=3`` + + * - ``MaxConnectionIdleTime`` + - | The maximum time that a connection can remain idle in the pool. When a connection + exceeds this limit, the {+driver-short+} closes the connection and removes it from + the pool. + | + | **Data Type**: ``TimeSpan`` + | **Default**: 10 minutes + | **Connection URI Example**: ``maxIdleTimeMS=60000`` + + * - ``MaxConnectionLifeTime`` + - | The maximum time that a connection can be pooled. When a connection exceeds this + limit, the {+driver-short+} closes the connection and removes it from the pool. + | + | **Data Type**: ``TimeSpan`` + | **Default**: 30 minutes + | **Connection URI Example**: ``maxLifeTimeMS=50000`` + + * - ``MaxConnectionPoolSize`` + - | 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**: ``integer`` + | **Default**: ``100`` + | **Connection URI Example**: ``maxPoolSize=150`` + + * - ``MinConnectionPoolSize`` + - | The minimum number of concurrent connections that the pool maintains. If + the number of open connections falls below this value due to network errors, + the {+driver-short+} attempts to create new connections to maintain this minimum. + | + | **Data Type**: ``integer`` + | **Default**: ``0`` + | **Connection URI Example**: ``minPoolSize=3`` + + * - ``SocketTimeout`` + - | The length of time that the {+driver-short+} waits for a response from the server + before timing out. + | + | **Data Type**: ``TimeSpan`` + | **Default**: OS default + | **Connection URI Example**: ``socketTimeoutMS=100000`` + + * - ``WaitQueueTimeout`` + - | How long a thread waits for a connection to become available in the connection pool + before timing out. + | + | **Data Type**: ``TimeSpan`` + | **Default**: 2 minutes + | **Connection URI Example**: ``waitQueueTimeoutMS=100000`` + +The following code creates a client with a maximum connection pool size of ``50`` by using the +``MaxConnectionPoolSize`` parameter: .. code-block:: csharp - var client = new MongoClient(""); + var settings = MongoClientSettings.FromConnectionString(""); + settings.MaxConnectionPoolSize = 50; + var client = new MongoClient(settings); + +The following code creates a client with the same configuration as the preceding example, +but uses a connection URI: + +.. code-block:: csharp + + var settings = MongoClientSettings.FromConnectionString("?maxPoolSize=50"); + var client = new MongoClient(settings); + +Additional Information +---------------------- + +To learn more about connection pools, see :manual:`Connection Pool Overview ` +in the {+mdb-server+} manual. + +API Documentation +~~~~~~~~~~~~~~~~~ -Create a client once for each process, and reuse it for all -operations. It is a common mistake to create a new client for each -request, which is very inefficient. +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: -There is no supported way to terminate a ``MongoClient`` in the driver. \ No newline at end of file +- `MongoClient <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClient.html>`__ +- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__