/ /

Manage Connections with Connection Pools

Overview

In this guide, you can learn about how the Ruby driver uses connection pools to manage connections to a MongoDB deployment and how you can configure connection pool settings in your application.

A connection pool is a cache of open database connections maintained by the Ruby driver. When your application requests a connection to MongoDB, the driver seamlessly gets 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 new connections are created by the Ruby driver.

Configure Connection Pools

Every Mongo::Client instance has a built-in connection pool for each server in your MongoDB topology. If you do not configure the min_pool_size option, connection pools open connections on demand to support concurrent requests to MongoDB in your application.

You can specify the following connection pool settings in your Mongo::Client instance:

Setting	Description
`max_pool_size`	The maximum number of concurrent connections that the pool maintains. If the number of in-use connections to a server reaches the specified value, the next request to that server waits until a connection becomes available. Setting this option to `0` creates an unlimited connection pool. Default: `100`
`max_connecting`	The maximum number of connections that each pool can establish concurrently. Default: `2`
`min_pool_size`	The minimum number of concurrent connections that the pool maintains. Default: `0`
`max_idle_time`	The maximum number of seconds that a connection can remain idle in the pool. Default: `0` (no limit)

max_pool_size

In addition to the connections needed to support your application's requests, each Mongo::Client instance opens up to two connections per server in your MongoDB topology for monitoring the server's state.

For example, a client connected to a three-node replica set opens six monitoring connections. If the application uses the default setting for max_pool_size and only queries the primary (default) node, then there can be at most 106 open connections and 100 connections in the connection pool. If the application uses a read preference to query the secondary nodes, those connection pools grow and there can be 306 total connections including the open monitoring connections.

To support high numbers of concurrent MongoDB requests within one process, you can increase max_pool_size.

The following code creates a Mongo::Client instance with a maximum connection pool size of 200 by specifying the max_pool_size option in the options object:

require 'mongo'
uri = "<connection-string>"
client = Mongo::Client(uri, {
    max_pool_size: 200
})

max_connecting

Connection pools rate-limit connection establishment. The max_connecting option determines the number of connections that the pool can create in parallel at any time. For example, if the value of max_connecting is 2, the third request that attempts to concurrently check out a connection succeeds only when one the following cases occurs:

The connection pool finishes creating a connection and there are fewer than max_pool_size connections in the pool.
An existing connection is checked back into the pool.

The following code creates a Mongo::Client instance with a maximum number of 2 connections to be established concurrently per pool by specifying the max_connecting option in the options object:

require 'mongo'
uri = "<connection-string>"
client = Mongo::Client(uri, {
    max_connecting: 2
})

min_pool_size

You can set the minimum number of connections to each server with the min_pool_size option. The driver ensures that there are always at least the number of connections set by the min_pool_size option in the connection pool. If connections are closed, causing the total number of connections (both in use and idle) to drop below the minimum, the driver opens more connections until the minimum is reached.

The following code creates a Mongo::Client instance with a minimum connection pool size of 10 by specifying the min_pool_size option in the options object:

require 'mongo'
uri = "<connection-string>"
client = Mongo::Client(uri, {
    min_pool_size: 10
})

Note

A Mongo::Client configured with max_idle_time and min_pool_size set to 0 is optimal for workloads with sustained periods of low activity. This configuration allows the connection pool to close unused connections during periods of inactivity.

max_idle_time

You can set the maximum number of milliseconds that a connection can remain idle in the pool by setting the max_idle_time option. Once a connection has been idle for max_idle_time, the connection pool removes and replaces it. This option defaults to 0 (no limit).

The following code creates a Mongo::Client instance with a maximum idle time of 10000 milliseconds (10 seconds) by specifying the max_idle_time setting in the options object:

require 'mongo'
uri = "<connection-string>"
client = Mongo::Client(uri, {
    max_idle_time: 10000
})

Closing Connections

When any request calls Mongo::Client.close(), the Ruby driver performs the following actions:

Closes all idle connections in the connection pool
Closes all connections that are in use as they are returned to the pool
Closes all connections that are in use only when the associated operations complete

Calling Mongo::Client.close() closes only inactive connections and does not directly terminate any ongoing operations.

Note

The Mongo::Client.close() method does close existing sessions and transactions, which might indirectly affect the behavior of ongoing operations and open cursors.

Avoid Connection Timeouts

Having a large connection pool does not always reduce reconnection requests. Consider the following example scenario:

An application has a connection pool size of 5 connections and has the timeout_ms option set to 5000 milliseconds.
Operations occur, on average, every 3000 milliseconds, and reconnection requests are frequent.
Each connection times out after 5000 milliseconds, which means that all connections must do something during those 5000 milliseconds to avoid closing.

In this scenario, each connection times out after 5000 milliseconds, requiring activity within this timeout period to avoid closure. However, one message every 3000 milliseconds isn't enough to keep all connections active, causing several of them to time out.

To avoid excessive connection timeouts, reduce the number of connections that the driver can maintain in the connection pool by specifying the max_pool_size option. To learn how to set the max_pool_size option, see the max_pool_size section of this guide.

API Documentation

For more information about creating a Mongo::Client object with the Ruby driver and specifying options, see the Options Hash section of the Mongo::Client API documentation.

Back

Limit Server Execution Time

Server Selection