Skip to content

Commit 9831d34

Browse files
mcmorisimcmorisi
committed
DOCSP-49058: Connection Pools
1 parent c0ae698 commit 9831d34

File tree

1 file changed

+133
-71
lines changed

1 file changed

+133
-71
lines changed

‎source/connect/connection-options/connection-pools.txt‎

Lines changed: 133 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,148 @@
1-
.. TODO: Connection Pools page
2-
31
.. _csharp-faq-connection-pool:
42
.. _csharp-connection-pools:
53

6-
How Does Connection Pooling Work in the {+driver-short+}?
7-
---------------------------------------------------------
4+
================
5+
Connection Pools
6+
================
7+
8+
.. facet::
9+
:name: genre
10+
:values: reference
11+
12+
.. contents:: On this page
13+
:local:
14+
:backlinks: none
15+
:depth: 2
16+
:class: singlecol
817

9-
Every ``MongoClient`` instance has a built-in connection pool for each server
10-
in your MongoDB topology. Connection pools open sockets on demand to
11-
support concurrent MongoDB operations in your multi-threaded application.
18+
Overview
19+
--------
1220

13-
The maximum size of each connection pool is set by the ``MaxConnectionPoolSize`` option, which
14-
defaults to ``100``. If the number of in-use connections to a server reaches
15-
the value of ``MaxConnectionPoolSize``, the next request to that server will wait
16-
until a connection becomes available. The following diagram illustrates a high-level view
21+
In this guide, you can learn about how the {+driver-short+} uses connection pools to manage
22+
connections to a MongoDB deployment and how you can configure connection pool settings
23+
in your application.
24+
25+
A connection pool is a cache of open database connections maintained by the {+driver-short+}.
26+
When your application requests a connection to MongoDB, the {+driver-short+} seamlessly
27+
gets a connection from the pool, performs operations, and returns the connection
28+
to the pool for reuse.
29+
30+
Connection pools help reduce application latency and the number of times new connections
31+
are created by the {+driver-short+}. The following diagram illustrates a high-level view
1732
of how the ``MongoClient`` manages a connection pool:
1833

1934
.. figure:: /includes/figures/CMAP_diagram.svg
2035
:alt: CMAP diagram
2136

22-
In addition to the sockets needed to support your application's threads,
23-
each ``MongoClient`` instance opens two additional sockets per server
24-
in your MongoDB topology for monitoring the server's state.
25-
For example, a client connected to a three-node replica set opens six
26-
monitoring sockets. If the application uses the default setting for
27-
``MaxConnectionPoolSize`` and only queries the primary (default) node, then
28-
there can be at most ``106`` total connections in use. If the
29-
application uses a :ref:`read preference <read-preference>` to query the
30-
secondary nodes, those connection pools grow and there can be
31-
``306`` total connections.
32-
33-
To support high numbers of concurrent MongoDB threads
34-
within one process, you can increase ``MaxConnectionPoolSize``.
35-
36-
The driver has a wait queue that limits the number of threads that can
37-
wait for a connection. The size of the wait queue is determined by the
38-
``WaitQueueMultiple`` option, which defaults to ``5``. To calculate the
39-
maximum wait queue size, the driver multiplies ``WaitQueueMultiple`` by
40-
``MaxConnectionPoolSize``. If you use the default value for each option,
41-
the wait queue size will be ``500``. You can also set the wait queue
42-
size by specifying the ``WaitQueueSize`` option, which overrides the
43-
other settings. However, we do not recommend changing the wait queue
44-
size from the default.
45-
46-
Connection pools are rate-limited. The ``MaxConnecting`` setting
47-
determines the number of connections that the pool can create in
48-
parallel at any time. For example, if the value of ``MaxConnecting`` is
49-
``2``, the third thread that attempts to concurrently check out a
50-
connection succeeds only in one of the following cases:
51-
52-
- One of the first two threads finishes creating a connection.
53-
- An existing connection is checked back into the pool.
54-
- The driver's ability to reuse existing connections improves due to
55-
rate-limits on connection creation.
56-
57-
You can set the minimum number of concurrent connections to
58-
each server by using the ``MinConnectionPoolSize`` option, which
59-
defaults to ``0``. The connection pool will be initialized with this
60-
number of sockets. If errors cause any sockets to close and the
61-
total number of sockets (both in-use and idle) drops below the minimum,
62-
the driver opens more sockets until the number reaches the minimum.
63-
64-
You can set the maximum number of milliseconds that a connection can
65-
remain idle in the pool by using the ``MaxConnectionIdleTime`` option.
66-
Once a connection is idle for ``MaxConnectionIdleTime``, the driver
67-
removes it. This option defaults to 10 minutes. If the pool size falls
68-
below ``MinConnectionPoolSize``, the driver removes *and* replaces the
69-
idle connection.
70-
71-
``MongoClient`` also has the ``MaxConnectionLifeTime`` option, which
72-
specifies the length of time, 30 minutes by default, that a connection
73-
can be pooled before expiring.
74-
75-
The following default configuration for a ``MongoClient`` works for most
76-
applications:
37+
Configuring Connection Pools
38+
----------------------------
39+
40+
You can specify the following connection pool settings in your ``MongoClient`` object or in
41+
your connection URI:
42+
43+
.. list-table::
44+
:widths: 30 70
45+
:header-rows: 1
46+
47+
* - Setting
48+
- Description
49+
50+
* - ``ConnectTimeout``
51+
- | The time that the {+driver-short+} waits when establishing a new
52+
connection before timing out.
53+
|
54+
| **Data Type**: ``TimeSpan``
55+
| **Default**: 30 seconds
56+
| **Connection URI Example**: ``connectTimeoutMS=0``
57+
58+
* - ``MaxConnecting``
59+
- | The maximum number of connections that each pool can establish concurrently.
60+
If this limit is reached, further requests wait until a connection is established
61+
or another in-use connection is checked back into the pool.
62+
|
63+
| **Data Type**: ``integer``
64+
| **Default**: ``2``
65+
| **Connection URI Example**: ``maxConnecting=3``
66+
67+
* - ``MaxConnectionIdleTime``
68+
- | The maximum time that a connection can remain idle in the pool. When a connection
69+
exceeds this limit, the {+driver-short+} closes the connection and removes it from
70+
the pool.
71+
|
72+
| **Data Type**: ``TimeSpan``
73+
| **Default**: 10 minutes
74+
| **Connection URI Example**: ``maxIdleTimeMS=60000``
75+
76+
* - ``MaxConnectionLifeTime``
77+
- The maximum time that a connection can be pooled. When a connection exceeds this
78+
limit, the {+driver-short+} closes the connection and removes it from the pool.
79+
|
80+
| **Data Type**: ``TimeSpan``
81+
| **Default**: 30 minutes
82+
| **Connection URI Example**: ``maxLifeTimeMS=50000``
83+
84+
* - ``MaxConnectionPoolSize``
85+
- | The maximum number of concurrent connections that the pool maintains.
86+
If the maximum pool size is reached, further requests wait until a connection
87+
becomes available.
88+
|
89+
| **Data Type**: ``integer``
90+
| **Default**: ``100``
91+
| **Connection URI Example**: ``maxPoolSize=150``
92+
93+
* - ``MinConnectionPoolSize``
94+
- | The minimum number of concurrent connections that the pool maintains. If
95+
the number of open connections falls below this value due to network errors,
96+
the {+driver-short+} attempts to create new connections to maintain this minimum.
97+
|
98+
| **Data Type**: ``integer``
99+
| **Default**: ``0``
100+
| **Connection URI Example**: ``minPoolSize=3``
101+
102+
* - ``SocketTimeout``
103+
- | The length of time that the {+driver-short+} waits for a response from the server
104+
before timing out.
105+
|
106+
| **Data Type**: ``TimeSpan``
107+
| **Default**: OS default
108+
| **Connection URI Example**: ``socketTimeoutMS=100000``
109+
110+
* - ``WaitQueueTimeout``
111+
- | How long a thread waits for a connection to become available in the connection pool
112+
before timing out.
113+
|
114+
| **Data Type**: ``TimeSpan``
115+
| **Default**: 2 minutes
116+
| **Connection URI Example**: ``waitQueueTimeoutMS=100000``
117+
118+
The following code creates a client with a maximum connection pool size of ``50`` by using the
119+
``MaxConnectionPoolSize`` parameter:
120+
121+
.. code-block:: csharp
122+
123+
var settings = MongoClientSettings.FromConnectionString("<connection URI>");
124+
settings.MaxConnectionPoolSize = 50;
125+
var client = new MongoClient(settings);
126+
127+
The following code creates a client with the same configuration as the preceding example,
128+
but uses a connection URI:
77129

78130
.. code-block:: csharp
79131

80-
var client = new MongoClient("<connection string>");
132+
var settings = MongoClientSettings.FromConnectionString("<hostname>?maxPoolSize=50");
133+
var client = new MongoClient(settings);
134+
135+
Additional Information
136+
----------------------
137+
138+
To learn more about connection pools, see :manual:`Connection Pool Overview </administration/connection-pool-overview/>`
139+
in the {+mdb-server+} manual.
140+
141+
API Documentation
142+
~~~~~~~~~~~~~~~~~
81143

82-
Create a client once for each process, and reuse it for all
83-
operations. It is a common mistake to create a new client for each
84-
request, which is very inefficient.
144+
To learn more about any of the methods or types discussed in this
145+
guide, see the following API documentation:
85146

86-
There is no supported way to terminate a ``MongoClient`` in the driver.
147+
- `MongoClient <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClient.html>`__
148+
- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__

0 commit comments

Comments
 (0)