Connection Pools

Overview

In this guide, you can learn about how Node.js 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 Node.js driver. When your application requests a connection to MongoDB, Node.js 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 Node.js driver.

Connection Pool Overview

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 requests to MongoDB in your application.

The maximum size of each connection pool is set by the maxPoolSize option, 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 will wait until a connection becomes available.

In addition to the sockets needed to support your application's requests, each MongoClient instance opens two more sockets 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 sockets. If the application uses the default setting for maxPoolSize and only queries the primary (default) node, then there can be at most 106 total 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.

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

Connection pools are rate-limited. The maxConnecting option determines the number of connections that the pool can create in parallel at any time. For example, if the value of maxConnecting 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 maxPoolSize connections in the pool.

• An existing connection is checked back into the pool.

• The driver's ability to reuse existing connections improves due to rate-limits on connection creation.

You can set the minimum number of concurrent connections to each server with the minPoolSize option, which defaults to 0. The driver initializes the connection pool with this number of sockets. If sockets are closed, causing the total number of sockets (both in use and idle) to drop below the minimum, more sockets are opened until the minimum is reached.

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

The following default configuration for a MongoClient works for most applications:

const client = new MongoClient("<connection string>");

MongoClient supports multiple concurrent requests. For each process, create a client and reuse it for all operations in a process. This practice is more efficient than creating a client for each request.

The driver does not limit the number of requests that can wait for sockets to become available, and it is the application's responsibility to limit the size of its pool to bound queuing during a load spike. Requests wait for the amount of time specified in the waitQueueTimeoutMS option, which defaults to 0 (no limit).

A request that waits more than the length of time defined by waitQueueTimeoutMS for a socket raises a connection error. Use this option if it is more important to bound the duration of operations during a load spike than it is to complete every operation.

When MongoClient.close() is called by any request, the driver closes all idle sockets and closes all sockets that are in use as they are returned to the pool. Calling MongoClient.close() closes only inactive sockets and does not directly terminate any ongoing operations. The driver closes any in-use sockets only when the associated operations complete. However, the MongoClient.close() method does close existing sessions and transactions, which might indirectly affect the behavior of ongoing operations and open cursors.

Avoid Socket Timeouts

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

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

One message every 3000 milliseconds is not enough to keep the sockets active, so several of the sockets will time out after 5000 milliseconds. To avoid excessive socket timeouts, reduce the number of connections that the driver can maintain in the connection pool by specifying the maxPoolSize option.

To specify the optional maxPoolSize setting for your MongoClient, declare it in the options object of the constructor as follows:

const client = new MongoClient(uri, {
  maxPoolSize: <integer value>,
});