Skip to content

Commit 0d31887

Browse files
mcmorisimcmorisi
authored
DOCSP-49058: Connection Pools (#616)
1 parent 012b476 commit 0d31887

File tree

1 file changed

+136
-71
lines changed

1 file changed

+136
-71
lines changed

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

Lines changed: 136 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,151 @@
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+
.. meta::
13+
:keywords: connection, client, latency
14+
15+
.. contents:: On this page
16+
:local:
17+
:backlinks: none
18+
:depth: 2
19+
:class: singlecol
820

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.
21+
Overview
22+
--------
1223

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
24+
In this guide, you can learn about how the {+driver-short+} uses connection pools to manage
25+
connections to a MongoDB deployment and how you can configure connection pool settings
26+
in your application.
27+
28+
A connection pool is a cache of open database connections maintained by the {+driver-short+}.
29+
When your application requests a connection to MongoDB, the {+driver-short+} seamlessly
30+
gets a connection from the pool, performs operations, and returns the connection
31+
to the pool for reuse.
32+
33+
Connection pools help reduce application latency and the number of times new connections
34+
are created by the {+driver-short+}. The following diagram illustrates a high-level view
1735
of how the ``MongoClient`` manages a connection pool:
1836

1937
.. figure:: /includes/figures/CMAP_diagram.svg
2038
:alt: CMAP diagram
2139

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:
40+
Configuring Connection Pools
41+
----------------------------
42+
43+
You can specify the following connection pool settings in your ``MongoClient`` object or in
44+
your connection URI:
45+
46+
.. list-table::
47+
:widths: 30 70
48+
:header-rows: 1
49+
50+
* - Setting
51+
- Description
52+
53+
* - ``ConnectTimeout``
54+
- | The maximum amount of time that the {+driver-short+} waits when establishing a new
55+
connection before timing out.
56+
|
57+
| **Data Type**: ``TimeSpan``
58+
| **Default**: 30 seconds
59+
| **Connection URI Example**: ``connectTimeoutMS=0``
60+
61+
* - ``MaxConnecting``
62+
- | The maximum number of connections that each pool can establish concurrently.
63+
If this limit is reached, further requests wait until a connection is established
64+
or another in-use connection is checked back into the pool.
65+
|
66+
| **Data Type**: ``integer``
67+
| **Default**: ``2``
68+
| **Connection URI Example**: ``maxConnecting=3``
69+
70+
* - ``MaxConnectionIdleTime``
71+
- | The maximum time that a connection can remain idle in the pool. When a connection
72+
exceeds this limit, the {+driver-short+} closes the connection and removes it from
73+
the pool.
74+
|
75+
| **Data Type**: ``TimeSpan``
76+
| **Default**: 10 minutes
77+
| **Connection URI Example**: ``maxIdleTimeMS=60000``
78+
79+
* - ``MaxConnectionLifeTime``
80+
- | The maximum time that a connection can be pooled. When a connection exceeds this
81+
limit, the {+driver-short+} closes the connection and removes it from the pool.
82+
|
83+
| **Data Type**: ``TimeSpan``
84+
| **Default**: 30 minutes
85+
| **Connection URI Example**: ``maxLifeTimeMS=50000``
86+
87+
* - ``MaxConnectionPoolSize``
88+
- | The maximum number of concurrent connections that the pool maintains.
89+
If the maximum pool size is reached, further requests wait until a connection
90+
becomes available.
91+
|
92+
| **Data Type**: ``integer``
93+
| **Default**: ``100``
94+
| **Connection URI Example**: ``maxPoolSize=150``
95+
96+
* - ``MinConnectionPoolSize``
97+
- | The minimum number of concurrent connections that the pool maintains. If
98+
the number of open connections falls below this value due to network errors,
99+
the {+driver-short+} attempts to create new connections to maintain this minimum.
100+
|
101+
| **Data Type**: ``integer``
102+
| **Default**: ``0``
103+
| **Connection URI Example**: ``minPoolSize=3``
104+
105+
* - ``SocketTimeout``
106+
- | The length of time that the {+driver-short+} waits for a response from the server
107+
before timing out.
108+
|
109+
| **Data Type**: ``TimeSpan``
110+
| **Default**: OS default
111+
| **Connection URI Example**: ``socketTimeoutMS=100000``
112+
113+
* - ``WaitQueueTimeout``
114+
- | How long a thread waits for a connection to become available in the connection pool
115+
before timing out.
116+
|
117+
| **Data Type**: ``TimeSpan``
118+
| **Default**: 2 minutes
119+
| **Connection URI Example**: ``waitQueueTimeoutMS=100000``
120+
121+
The following code creates a client with a maximum connection pool size of ``50`` by using the
122+
``MaxConnectionPoolSize`` parameter:
77123

78124
.. code-block:: csharp
79125

80-
var client = new MongoClient("<connection string>");
126+
var settings = MongoClientSettings.FromConnectionString("<connection URI>");
127+
settings.MaxConnectionPoolSize = 50;
128+
var client = new MongoClient(settings);
129+
130+
The following code creates a client with the same configuration as the preceding example,
131+
but uses a connection URI:
132+
133+
.. code-block:: csharp
134+
135+
var settings = MongoClientSettings.FromConnectionString("<hostname>?maxPoolSize=50");
136+
var client = new MongoClient(settings);
137+
138+
Additional Information
139+
----------------------
140+
141+
To learn more about connection pools, see :manual:`Connection Pool Overview </administration/connection-pool-overview/>`
142+
in the {+mdb-server+} manual.
143+
144+
API Documentation
145+
~~~~~~~~~~~~~~~~~
81146

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.
147+
To learn more about any of the methods or types discussed in this
148+
guide, see the following API documentation:
85149

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

0 commit comments

Comments
 (0)