Skip to content

Commit 6c85c3b

Browse files
norareidynorareidy
authored
DOCSP-51325: Connection pools (#119)
* DOCSP-51325: Connection pools * edits * edits * keywords * link * imports * code edit * move file
1 parent cf2870d commit 6c85c3b

File tree

4 files changed

+243
-17
lines changed

4 files changed

+243
-17
lines changed

‎source/connect/connection-options.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Specify Connection Options
1919
Server Selection </connect/connection-options/server-selection>
2020
Stable API </connect/connection-options/stable-api>
2121
Limit Server Execution Time </connect/connection-options/csot>
22-
Connection Pools </connect/connection-pools>
22+
Connection Pools </connect/connection-options/connection-pools>
2323

2424
Overview
2525
--------

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

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
.. _kotlin-sync-connection-pools:
2+
3+
================
4+
Connection Pools
5+
================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: concurrent, request, kotlin
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn about how the {+driver-short+} uses connection pools to manage
24+
connections to a MongoDB deployment. You can specify connection pool settings
25+
in your application to configure this behavior.
26+
27+
A connection pool is a cache of open database connections maintained by the {+driver-short+}.
28+
When your application requests a connection to MongoDB, the driver retrieves
29+
a connection from the pool, performs operations, and returns the connection
30+
to the pool for reuse.
31+
32+
Connection pools help reduce application latency and the number of times the driver
33+
creates new connections.
34+
35+
Create a Connection Pool
36+
------------------------
37+
38+
Each ``MongoClient`` instance has a built-in connection pool for each server in your
39+
MongoDB topology. If you do not configure the ``minPoolSize`` option, connection
40+
pools open sockets on demand. These sockets support concurrent MongoDB
41+
operations in your application.
42+
43+
When you instantiate a new ``MongoClient``, the client opens two sockets per server
44+
in your MongoDB topology to monitor the server's state.
45+
46+
For example, a client connected to a three-node replica set opens six monitoring
47+
sockets. If the application uses the default setting for ``maxPoolSize`` and
48+
only queries the primary node, there can be at most ``106`` open
49+
sockets and ``100`` connections in the connection pool. If the application uses
50+
a :ref:`read preference <kotlin-sync-configure>` to query the secondary nodes, there
51+
can be ``306`` total connections.
52+
53+
For efficiency, create a client once for each process and reuse it for all
54+
operations. Avoid creating a new client for each request because this will
55+
increase latency.
56+
57+
Configure a Connection Pool
58+
---------------------------
59+
60+
You can specify settings for your connection pool by using either a connection
61+
string or a ``MongoClientSettings`` object.
62+
63+
Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to
64+
see the corresponding syntax:
65+
66+
.. tabs::
67+
68+
.. tab:: Connection String
69+
:tabid: uri
70+
71+
The following table describes connection pool options that you can set
72+
in your connection string:
73+
74+
.. list-table::
75+
:widths: 25,75
76+
:header-rows: 1
77+
78+
* - Option
79+
- Description
80+
81+
* - ``maxConnecting``
82+
83+
- Sets the maximum number of connections a pool may establish
84+
concurrently.
85+
86+
*Default:* ``2``
87+
88+
* - ``maxIdleTimeMS``
89+
90+
- Sets the maximum number of milliseconds that a connection can
91+
remain idle in the pool before it is removed and closed.
92+
93+
*Default:* ``0``
94+
95+
* - ``maxPoolSize``
96+
97+
- Sets the maximum number of connections that can be open in a pool. If an
98+
operation needs a new connection while the connection pool has
99+
the maximum number of open connections, the operation
100+
waits for a new connection to open. To limit this
101+
waiting time, use the single timeout setting. To learn more,
102+
see the :ref:`kotlin-sync-csot` guide.
103+
104+
*Default:* ``100``
105+
106+
* - ``minPoolSize``
107+
108+
- Sets the minimum number of connections that can be open in a pool.
109+
The value of ``minPoolSize`` must be less than
110+
the value of ``maxPoolSize``.
111+
112+
*Default*: ``0``
113+
114+
* - ``maxLifeTimeMS``
115+
116+
- Sets the maximum amount of time, in milliseconds, the driver
117+
can continue to use a pooled connection before closing the
118+
connection. A value of ``0`` indicates that there is no upper bound on
119+
how long the driver can keep a pooled connection open.
120+
121+
*Default*: ``0``
122+
123+
To learn more about these options, see the `ConnectionString
124+
<{+core-api+}/ConnectionString.html>`__ API documentation.
125+
126+
.. tab:: MongoClientSettings
127+
:tabid: MongoClient
128+
129+
To specify connection pool settings in a ``MongoClientSettings`` object,
130+
chain the ``applyToConnectionPoolSettings()`` method to the ``MongoClientSettings`` builder.
131+
Pass a ``ConnectionPoolSettings.Builder`` block as a parameter to the
132+
``applyToConnectionPoolSettings()`` method.
133+
134+
The following table describes the setter methods you can use in a
135+
``ConnectionPoolSettings.Builder`` block to configure the connection pool:
136+
137+
.. list-table::
138+
:widths: 40 60
139+
:header-rows: 1
140+
141+
* - Method
142+
- Description
143+
144+
* - ``addConnectionPoolListener()``
145+
- Adds a listener for connection pool-related events.
146+
147+
* - ``applyConnectionString()``
148+
- Applies the settings from a ``ConnectionString`` object.
149+
150+
* - ``applySettings()``
151+
- Uses the connection pool settings specified in a
152+
``ConnectionPoolSettings`` object.
153+
154+
* - ``maintenanceFrequency()``
155+
- Sets the frequency for running connection pool maintenance jobs.
156+
157+
* - ``maintenanceInitialDelay()``
158+
- Sets the time to wait before running the first maintenance job
159+
on the connection pool.
160+
161+
* - ``maxConnectionIdleTime()``
162+
- Sets the maximum time a connection can be idle before it's closed.
163+
164+
* - ``maxConnectionLifeTime()``
165+
- Sets the maximum time a pooled connection can be open before it's
166+
closed.
167+
168+
* - ``maxSize()``
169+
- Sets the maximum number of connections that can be open in a pool.
170+
171+
*Default*: ``100``
172+
173+
* - ``maxWaitTime()``
174+
- Sets the maximum time to wait for an available connection.
175+
176+
*Default*: ``2`` minutes
177+
178+
* - ``minSize()``
179+
- Sets the minimum number of connections that can be open in a pool.
180+
181+
*Default*: ``0``
182+
183+
To learn more about these methods, see the `ConnectionPoolSettings.Builder
184+
<{+core-api+}/connection/ConnectionPoolSettings.Builder.html>`__
185+
API documentation.
186+
187+
Example
188+
~~~~~~~
189+
190+
The following example shows how to create a connection pool that
191+
has maximum size of ``50`` connections.
192+
193+
Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to
194+
see the corresponding syntax:
195+
196+
.. tabs::
197+
198+
.. tab:: Connection String
199+
:tabid: uri
200+
201+
.. literalinclude:: /includes/connect/connection-pools.kt
202+
:start-after: start-uri-option
203+
:end-before: end-uri-option
204+
:language: kotlin
205+
:dedent:
206+
207+
.. tab:: MongoClientSettings
208+
:tabid: MongoClient
209+
210+
.. literalinclude:: /includes/connect/connection-pools.kt
211+
:start-after: start-client-settings
212+
:end-before: end-client-settings
213+
:language: kotlin
214+
:dedent:
215+
216+
Additional Information
217+
----------------------
218+
219+
To learn more about using a connection pool, see
220+
:manual:`Connection Pool Overview </administration/connection-pool-overview>`
221+
in the {+mdb-server+} manual.

‎source/connect/connection-pools.txt

Lines changed: 0 additions & 16 deletions
This file was deleted.

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

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

0 commit comments

Comments
 (0)