Skip to content

Commit 8d99216

Browse files
norareidynorareidy
committed
DOCSP-51325: Connection pools
1 parent 6f62210 commit 8d99216

File tree

2 files changed

+219
-2
lines changed

2 files changed

+219
-2
lines changed

‎source/connect/connection-pools.txt

Lines changed: 195 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,200 @@ Connection Pools
1010
:depth: 2
1111
:class: singlecol
1212

13+
.. facet::
14+
:name: genre
15+
:values: reference
1316

14-
.. _kotlin-sync-connection-pool-settings:
17+
Overview
18+
--------
1519

16-
.. TODO
20+
In this guide, you can learn about how the {+driver-short+} uses connection pools to manage
21+
connections to a MongoDB deployment. You can specify connection pool settings
22+
in your application to configure this behavior.
23+
24+
A connection pool is a cache of open database connections maintained by the {+driver-short+}.
25+
When your application requests a connection to MongoDB, the driver retrieves
26+
a connection from the pool, performs operations, and returns the connection
27+
to the pool for reuse.
28+
29+
Connection pools help reduce application latency and the number of times the driver
30+
creates new connections.
31+
32+
Create a Connection Pool
33+
------------------------
34+
35+
Every ``MongoClient`` instance has a built-in connection pool for each server
36+
in your MongoDB topology. Connection pools open sockets on demand to support
37+
concurrent MongoDB operations in your multi-threaded application.
38+
39+
The ``maxPoolSize`` option sets the maximum size of each connection pool, which
40+
defaults to 100. If the number of in-use connections to a server reaches the
41+
value of ``maxPoolSize``, the next request to that server waits until a
42+
connection becomes available.
43+
44+
Each ``MongoClient`` instance opens two more sockets per server in your MongoDB
45+
topology to monitor the server's state.
46+
47+
Configure a Connection Pool
48+
---------------------------
49+
50+
You can specify settings for your connection pool by using either a connection
51+
string or a ``MongoClientSettings`` object.
52+
53+
Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to
54+
see the corresponding syntax:
55+
56+
.. tabs::
57+
58+
.. tab:: Connection String
59+
:tabid: uri
60+
61+
The following table describes connection pool options that you can set
62+
in your connection string:
63+
64+
.. list-table::
65+
:widths: 25,75
66+
:header-rows: 1
67+
68+
* - Option
69+
- Description
70+
71+
* - ``maxConnecting``
72+
73+
- Sets the maximum number of connections a pool may establish
74+
concurrently.
75+
76+
*Default:* ``2``
77+
78+
* - ``maxIdleTimeMS``
79+
80+
- Sets the maximum number of milliseconds that a connection can
81+
remain idle in the pool before it is removed and closed.
82+
83+
*Default:* ``0``
84+
85+
* - ``maxPoolSize``
86+
87+
- Sets the maximum number of connections that can be open in a pool. If an
88+
operation needs a new connection while the connection pool has
89+
the maximum number of open connections, the operation
90+
waits for a new connection to open. To limit this
91+
waiting time, use the single timeout setting. To learn more,
92+
see the :ref:`kotlin-sync-csot` guide.
93+
94+
*Default:* ``100``
95+
96+
* - ``minPoolSize``
97+
98+
- Sets the minimum number of connections that can be open in a pool.
99+
The value of ``minPoolSize`` must be less than
100+
the value of ``maxPoolSize``.
101+
102+
*Default*: ``0``
103+
104+
* - ``maxLifeTimeMS``
105+
106+
- Sets the maximum amount of time, in milliseconds, the driver
107+
can continue to use a pooled connection before closing the
108+
connection. A value of ``0`` indicates that there is no upper bound on
109+
how long the driver can keep a pooled connection open.
110+
111+
*Default*: ``0``
112+
113+
To learn more about these options, see the `ConnectionString
114+
<{+core-api+}/ConnectionString.html>`__ API documentation.
115+
116+
.. tab:: MongoClientSettings
117+
:tabid: MongoClient
118+
119+
To specify connection pool settings in a ``MongoClientSettings`` object,
120+
chain the ``applyToConnectionPoolSettings()`` method to the ``MongoClientSettings`` builder.
121+
122+
The following table describes the setter methods you can use inside ``applyToConnectionPoolSettings()``
123+
to configure the connection pool:
124+
125+
.. list-table::
126+
:widths: 40 60
127+
:header-rows: 1
128+
129+
* - Method
130+
- Description
131+
132+
* - ``addConnectionPoolListener()``
133+
- Adds a listener for connection pool-related events.
134+
135+
* - ``applyConnectionString()``
136+
- Applies the settings from a ``ConnectionString`` object.
137+
138+
* - ``applySettings()``
139+
- Uses the connection pool settings specified in a
140+
``ConnectionPoolSettings`` object.
141+
142+
* - ``maintenanceFrequency()``
143+
- Sets the frequency for running connection pool maintenance jobs.
144+
145+
* - ``maintenanceInitialDelay()``
146+
- Sets the time to wait before running the first maintenance job
147+
on the connection pool.
148+
149+
* - ``maxConnectionIdleTime()``
150+
- Sets the maximum time a connection can be idle before it's closed.
151+
152+
* - ``maxConnectionLifeTime()``
153+
- Sets the maximum time a pooled connection can be open before it's
154+
closed.
155+
156+
* - ``maxSize()``
157+
- Sets the maximum number of connections that can be open in a pool.
158+
159+
*Default*: ``100``
160+
161+
* - ``maxWaitTime()``
162+
- Sets the maximum time to wait for an available connection.
163+
164+
*Default*: ``2`` minutes
165+
166+
* - ``minSize()``
167+
- Sets the minimum number of connections that can be open in a pool.
168+
169+
*Default*: ``0``
170+
171+
To learn more about these methods, see the `applyToConnectionPoolSettings()
172+
<{+core-api+}/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__
173+
API documentation.
174+
175+
Example
176+
~~~~~~~
177+
178+
The following example shows how to create a connection pool that
179+
has maximum size of ``50`` connections.
180+
181+
Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to
182+
see the corresponding syntax:
183+
184+
.. tabs::
185+
186+
.. tab:: Connection String
187+
:tabid: uri
188+
189+
.. literalinclude:: /includes/connect/connection-pools.kt
190+
:start-after: start-uri-option
191+
:end-before: end-uri-option
192+
:language: kotlin
193+
:dedent:
194+
195+
.. tab:: MongoClientSettings
196+
:tabid: MongoClient
197+
198+
.. literalinclude:: /includes/connect/connection-pools.kt
199+
:start-after: start-client-settings
200+
:end-before: end-client-settings
201+
:language: kotlin
202+
:dedent:
203+
204+
Additional Information
205+
----------------------
206+
207+
To learn more about using a connection pool, see the
208+
:manual:`Connection Pool </administration/connection-pool-overview>`
209+
entry in the {+mdb-server+} manual.

‎source/includes/connect/connection-pools.kt

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import com.mongodb.ConnectionString
2+
import com.mongodb.MongoClientSettings
3+
import com.mongodb.ServerAddress
4+
import com.mongodb.ServerApi
5+
import com.mongodb.ServerApiVersion
6+
import com.mongodb.kotlin.client.MongoClient
7+
8+
fun main() {
9+
// start-uri-option
10+
val uri = "mongodb://<host>:<port>/?maxPoolSize=50"
11+
val client = MongoClient.create(uri)
12+
// end-uri-option
13+
14+
// start-client-settings
15+
val mongoClient = MongoClient.create(
16+
MongoClientSettings.builder()
17+
.applyConnectionString(ConnectionString("<connection string>"))
18+
.applyToConnectionPoolSettings { builder ->
19+
builder.maxSize(50)
20+
}
21+
.build()
22+
)
23+
// end-client-settings
24+
}

0 commit comments

Comments
 (0)