From 8d992169a166c020d6a1362a1c1a6d6b7b942fb4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 17 Jul 2025 12:10:24 -0400 Subject: [PATCH 1/8] DOCSP-51325: Connection pools --- source/connect/connection-pools.txt | 197 +++++++++++++++++++- source/includes/connect/connection-pools.kt | 24 +++ 2 files changed, 219 insertions(+), 2 deletions(-) create mode 100644 source/includes/connect/connection-pools.kt diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt index e8b95f19..bfee717c 100644 --- a/source/connect/connection-pools.txt +++ b/source/connect/connection-pools.txt @@ -10,7 +10,200 @@ Connection Pools :depth: 2 :class: singlecol +.. facet:: + :name: genre + :values: reference -.. _kotlin-sync-connection-pool-settings: +Overview +-------- -.. TODO \ No newline at end of file +In this guide, you can learn about how the {+driver-short+} uses connection pools to manage +connections to a MongoDB deployment. You can specify connection pool settings +in your application to configure this behavior. + +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 retrieves +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 the driver +creates new connections. + +Create a Connection Pool +------------------------ + +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. + +The ``maxPoolSize`` option sets the maximum size of each connection pool, which +defaults to 100. If the number of in-use connections to a server reaches the +value of ``maxPoolSize``, the next request to that server waits until a +connection becomes available. + +Each ``MongoClient`` instance opens two more sockets per server in your MongoDB +topology to monitor the server's state. + +Configure a Connection Pool +--------------------------- + +You can specify settings for your connection pool by using either a connection +string or a ``MongoClientSettings`` object. + +Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to +see the corresponding syntax: + +.. tabs:: + + .. tab:: Connection String + :tabid: uri + + The following table describes connection pool options that you can set + in your connection string: + + .. list-table:: + :widths: 25,75 + :header-rows: 1 + + * - Option + - Description + + * - ``maxConnecting`` + + - Sets the maximum number of connections a pool may establish + concurrently. + + *Default:* ``2`` + + * - ``maxIdleTimeMS`` + + - Sets the maximum number of milliseconds that a connection can + remain idle in the pool before it is removed and closed. + + *Default:* ``0`` + + * - ``maxPoolSize`` + + - Sets the maximum number of connections that can be open in a pool. If an + operation needs a new connection while the connection pool has + the maximum number of open connections, the operation + waits for a new connection to open. To limit this + waiting time, use the single timeout setting. To learn more, + see the :ref:`kotlin-sync-csot` guide. + + *Default:* ``100`` + + * - ``minPoolSize`` + + - Sets the minimum number of connections that can be open in a pool. + The value of ``minPoolSize`` must be less than + the value of ``maxPoolSize``. + + *Default*: ``0`` + + * - ``maxLifeTimeMS`` + + - Sets the maximum amount of time, in milliseconds, the driver + can continue to use a pooled connection before closing the + connection. A value of ``0`` indicates that there is no upper bound on + how long the driver can keep a pooled connection open. + + *Default*: ``0`` + + To learn more about these options, see the `ConnectionString + <{+core-api+}/ConnectionString.html>`__ API documentation. + + .. tab:: MongoClientSettings + :tabid: MongoClient + + To specify connection pool settings in a ``MongoClientSettings`` object, + chain the ``applyToConnectionPoolSettings()`` method to the ``MongoClientSettings`` builder. + + The following table describes the setter methods you can use inside ``applyToConnectionPoolSettings()`` + to configure the connection pool: + + .. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``addConnectionPoolListener()`` + - Adds a listener for connection pool-related events. + + * - ``applyConnectionString()`` + - Applies the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the connection pool settings specified in a + ``ConnectionPoolSettings`` object. + + * - ``maintenanceFrequency()`` + - Sets the frequency for running connection pool maintenance jobs. + + * - ``maintenanceInitialDelay()`` + - Sets the time to wait before running the first maintenance job + on the connection pool. + + * - ``maxConnectionIdleTime()`` + - Sets the maximum time a connection can be idle before it's closed. + + * - ``maxConnectionLifeTime()`` + - Sets the maximum time a pooled connection can be open before it's + closed. + + * - ``maxSize()`` + - Sets the maximum number of connections that can be open in a pool. + + *Default*: ``100`` + + * - ``maxWaitTime()`` + - Sets the maximum time to wait for an available connection. + + *Default*: ``2`` minutes + + * - ``minSize()`` + - Sets the minimum number of connections that can be open in a pool. + + *Default*: ``0`` + + To learn more about these methods, see the `applyToConnectionPoolSettings() + <{+core-api+}/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ + API documentation. + +Example +~~~~~~~ + +The following example shows how to create a connection pool that +has maximum size of ``50`` connections. + +Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to +see the corresponding syntax: + +.. tabs:: + + .. tab:: Connection String + :tabid: uri + + .. literalinclude:: /includes/connect/connection-pools.kt + :start-after: start-uri-option + :end-before: end-uri-option + :language: kotlin + :dedent: + + .. tab:: MongoClientSettings + :tabid: MongoClient + + .. literalinclude:: /includes/connect/connection-pools.kt + :start-after: start-client-settings + :end-before: end-client-settings + :language: kotlin + :dedent: + +Additional Information +---------------------- + +To learn more about using a connection pool, see the +:manual:`Connection Pool ` +entry in the {+mdb-server+} manual. diff --git a/source/includes/connect/connection-pools.kt b/source/includes/connect/connection-pools.kt new file mode 100644 index 00000000..00f9d8af --- /dev/null +++ b/source/includes/connect/connection-pools.kt @@ -0,0 +1,24 @@ +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.ServerAddress +import com.mongodb.ServerApi +import com.mongodb.ServerApiVersion +import com.mongodb.kotlin.client.MongoClient + +fun main() { + // start-uri-option + val uri = "mongodb://:/?maxPoolSize=50" + val client = MongoClient.create(uri) + // end-uri-option + + // start-client-settings + val mongoClient = MongoClient.create( + MongoClientSettings.builder() + .applyConnectionString(ConnectionString("")) + .applyToConnectionPoolSettings { builder -> + builder.maxSize(50) + } + .build() + ) + // end-client-settings +} \ No newline at end of file From b17bbb6c50a77d3b8f379963d78db84016ab9baa Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 17 Jul 2025 12:17:35 -0400 Subject: [PATCH 2/8] edits --- source/connect/connection-pools.txt | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt index bfee717c..0b5d3e1e 100644 --- a/source/connect/connection-pools.txt +++ b/source/connect/connection-pools.txt @@ -32,17 +32,24 @@ creates new connections. Create a Connection Pool ------------------------ -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. - -The ``maxPoolSize`` option sets the maximum size of each connection pool, which -defaults to 100. If the number of in-use connections to a server reaches the -value of ``maxPoolSize``, the next request to that server waits until a -connection becomes available. - -Each ``MongoClient`` instance opens two more sockets per server in your MongoDB -topology to monitor the server's state. +Each ``MongoClient`` instance has a built-in connection pool for each server in your +MongoDB topology. If you do not configure the ``minPoolSize`` option, connection +pools open sockets on demand. These sockets support concurrent MongoDB +operations in your application. + +When you instantiate a new ``MongoClient``, the client opens two sockets per server +in your MongoDB topology to monitor 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 ``maxPoolSize`` and +only queries the primary node, there can be at most ``106`` open +sockets and ``100`` connections in the connection pool. If the application uses +a :ref:`read preference ` to query the secondary nodes, there +can be ``306`` total connections. + +For efficiency, create a client once for each process and reuse it for all +operations. Avoid creating a new client for each request because this will +increase latency. Configure a Connection Pool --------------------------- From 1f5cbfdf44c689bd9cb81eeb70dcf443d46dbf4b Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 17 Jul 2025 13:38:25 -0400 Subject: [PATCH 3/8] edits --- source/connect/connection-pools.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt index 0b5d3e1e..e66dd04a 100644 --- a/source/connect/connection-pools.txt +++ b/source/connect/connection-pools.txt @@ -124,10 +124,12 @@ see the corresponding syntax: :tabid: MongoClient To specify connection pool settings in a ``MongoClientSettings`` object, - chain the ``applyToConnectionPoolSettings()`` method to the ``MongoClientSettings`` builder. + chain the ``applyToConnectionPoolSettings()`` method to the ``MongoClientSettings`` builder. + Pass a ``ConnectionPoolSettings.Builder`` block as a parameter to the + ``applyToConnectionPoolSettings()`` method. - The following table describes the setter methods you can use inside ``applyToConnectionPoolSettings()`` - to configure the connection pool: + The following table describes the setter methods you can use in a + ``ConnectionPoolSettings.Builder`` block to configure the connection pool: .. list-table:: :widths: 40 60 @@ -175,8 +177,8 @@ see the corresponding syntax: *Default*: ``0`` - To learn more about these methods, see the `applyToConnectionPoolSettings() - <{+core-api+}/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ + To learn more about these methods, see the `ConnectionPoolSettings.Builder + <{+core-api+}/connection/ConnectionPoolSettings.Builder.html>`__ API documentation. Example From 773e4a06c06f45577784a5ec562e024dddbbe98b Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 17 Jul 2025 13:40:29 -0400 Subject: [PATCH 4/8] keywords --- source/connect/connection-pools.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt index e66dd04a..31391586 100644 --- a/source/connect/connection-pools.txt +++ b/source/connect/connection-pools.txt @@ -14,6 +14,9 @@ Connection Pools :name: genre :values: reference +.. meta:: + :keywords: concurrent, request, kotlin + Overview -------- From eba5f23e6d0b88b2b2226c23d6fd7e9dd3399375 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 17 Jul 2025 13:41:01 -0400 Subject: [PATCH 5/8] link --- source/connect/connection-pools.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt index 31391586..16d266aa 100644 --- a/source/connect/connection-pools.txt +++ b/source/connect/connection-pools.txt @@ -216,6 +216,6 @@ see the corresponding syntax: Additional Information ---------------------- -To learn more about using a connection pool, see the -:manual:`Connection Pool ` -entry in the {+mdb-server+} manual. +To learn more about using a connection pool, see +:manual:`Connection Pool Overview ` +in the {+mdb-server+} manual. From 2932c0899537976e7c1d8e31ed2df3815a5b2fb5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 17 Jul 2025 13:42:22 -0400 Subject: [PATCH 6/8] imports --- source/includes/connect/connection-pools.kt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/source/includes/connect/connection-pools.kt b/source/includes/connect/connection-pools.kt index 00f9d8af..3715403a 100644 --- a/source/includes/connect/connection-pools.kt +++ b/source/includes/connect/connection-pools.kt @@ -1,9 +1,6 @@ import com.mongodb.ConnectionString -import com.mongodb.MongoClientSettings -import com.mongodb.ServerAddress -import com.mongodb.ServerApi -import com.mongodb.ServerApiVersion import com.mongodb.kotlin.client.MongoClient +import com.mongodb.MongoClientSettings fun main() { // start-uri-option From 1420a5d62415497e84d9cf4039a14423848529b1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 17 Jul 2025 13:44:08 -0400 Subject: [PATCH 7/8] code edit --- source/includes/connect/connection-pools.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/connect/connection-pools.kt b/source/includes/connect/connection-pools.kt index 3715403a..b1534181 100644 --- a/source/includes/connect/connection-pools.kt +++ b/source/includes/connect/connection-pools.kt @@ -11,7 +11,7 @@ fun main() { // start-client-settings val mongoClient = MongoClient.create( MongoClientSettings.builder() - .applyConnectionString(ConnectionString("")) + .applyConnectionString(ConnectionString("mongodb://:/")) .applyToConnectionPoolSettings { builder -> builder.maxSize(50) } From 0bf8f4153129b76f0c8416558e0e466f12ec5db5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 17 Jul 2025 15:37:27 -0400 Subject: [PATCH 8/8] move file --- source/connect/connection-options.txt | 2 +- source/connect/{ => connection-options}/connection-pools.txt | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename source/connect/{ => connection-options}/connection-pools.txt (100%) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 16be34bc..191dec34 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -18,7 +18,7 @@ Specify Connection Options Network Compression Stable API Limit Server Execution Time - Connection Pools + Connection Pools Overview -------- diff --git a/source/connect/connection-pools.txt b/source/connect/connection-options/connection-pools.txt similarity index 100% rename from source/connect/connection-pools.txt rename to source/connect/connection-options/connection-pools.txt