FAQ

How Does Connection Pooling Work in the Node Driver?

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 additional 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, so you cannot interrupt or terminate any ongoing operations by using this method. The driver closes these sockets only when the process completes.

How to fix a "MongoServerSelectionError: connect ECONNREFUSED ::1:27017" error?

Beginning with version 17, Node.js defaults to using IPV6. You have a few options to resolve this error:

• Start your mongod in IPV6 mode with the --ipv6 flag, or setting the net.ipv6 option to true in your configuration file.

  Starting mongod with the --ipv6 flag

  mongod --ipv6
  Setting the net.ipv6 option in the configuration file

  net:
    ipv6: true

• Explicitly use IPV4 by specifying family: 4 as an option to your MongoClient.

  const client = new MongoClient(uri, {
    family: 4,
  });

What Is the Difference Between "connectTimeoutMS", "socketTimeoutMS" and "maxTimeMS"?

To specify the optional settings for your MongoClient, declare one or more available settings in the options object of the constructor as follows:

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

To see all the available settings, see the MongoClientOptions API Documentation.

To specify maxTimeMS, chain the maxTimeMS() method with a timeout specification to an operation that returns a Cursor:

const cursor = collection.find({}).maxTimeMS(50);

How Can I Prevent the Driver From Hanging During Connection or From Spending Too Long Trying to Reach Unreachable Replica Sets?

To prevent the driver from hanging during connection or to prevent the driver from spending too long trying to reach unreachable replica sets, you can set the connectTimeoutMS option of your connection options. Generally, you should ensure that the connectTimeoutMS setting is not lower than the longest network latency you have to a member of the set. If one of the secondary members is on the other side of the planet and has a latency of 10000 milliseconds, setting the connectTimeoutMS to anything lower will prevent the driver from ever connecting to that member.

What Happens to Running Operations If the Client Disconnects?

Starting in MongoDB Server version 4.2, the server terminates running operations such as aggregations and find operations if the client disconnects. To see a full list of operations affected by this behavior, see the Server version 4.2 release notes in the Server manual.

Other operations, such as write operations, continue to run on the MongoDB Server even if the client disconnects. This behavior can cause data inconsistencies if your application retries the operation after the client disconnects.

How Can I Confirm That the Driver Closed Unusable Sockets?

If you experience unexpected network behavior or if a MongoDB process fails with an error, you may not receive confirmation that the driver correctly closed the corresponding socket.

To make sure that the driver correctly closes the socket in these cases, set the socketTimeoutMS option. When a MongoDB process times out, the driver will close the socket. We recommend that you select a value for socketTimeoutMS that is two to three times as long as the expected duration of the slowest operation that your application executes.

How Can I Prevent Sockets From Timing Out Before They Become Active?

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>,
});

What Does a Value of "0" mean for "connectTimeoutMS" and "socketTimeoutMS"?

If you set the value of connectTimeoutMS or socketTimeoutMS to 0, your application will use the operating system's default socket timeout value.

How Can I Prevent Long-Running Operations From Slowing Down the Server?

You can prevent long-running operations from slowing down the server by specifying a timeout value. You can chain the maxTimeMS() method to an operation that returns a Cursor to set a timeout on a specific action.

The following example shows how you can chain the maxTimeMS() method to an operation that returns a Cursor:

// Execute a find command
await collection
  .find({ $where: "sleep(100) || true" })
  .maxTimeMS(50);

What Does the "keepAlive" Setting Do?

keepAlive is a connection-setting that sets the number of milliseconds to wait before initiating a TLS keepAlive on a TCP Socket. The keepAlive option will keep a socket alive by sending periodic probes to MongoDB. However, this only works if the operating system supports SO_KEEPALIVE .

What Can I Do If I'm Experiencing Unexpected Network Behavior?

Internal firewalls that exist between application servers and MongoDB are often misconfigured and are overly aggressive in their removal of socket connections.

If you experience unexpected network behavior, here are some things to check:

1. The firewall should send a FIN packet when closing a socket, allowing the driver to detect that the socket is closed.

2. The firewall should allow keepAlive probes.

What Can I Do If I'm Getting "ECONNRESET" When Calling "client.connect()"?

In most operating systems, each connection is associated with a file descriptor. There is typically a limit set by the operating system on the number of file descriptors used by a single process. An ECONNRESET error can occur if the connection pool size surpasses the limit of file descriptors.

Consider the following operation:

1
const uri = "mongodb://localhost:27017/test?maxPoolSize=5000";
2
// create a new MongoClient
3
const client = new MongoClient(uri);
4
5
await client.connect(err => {
6
  // connection
7
});

If this operation causes an ECONNRESET error, you may have run into the file descriptor limit for your Node.js process. In that case you must increase the number of file descriptors for the Node.js process. On MacOS and Linux you do this with the ulimit shell command.

ulimit -n 6000

This sets the maximum number of file descriptors for the process to 6000, allowing Node.js to connect with a pool size of 5000 sockets.

How Can I Prevent a Slow Operation From Delaying Other Operations?

When you use the same MongoClient instance to run multiple MongoDB operations concurrently, a slow operation can cause delays to other operations. Slow operations keep a connection to MongoDB occupied, which can cause other operations to wait until an additional connection becomes available.

If you suspect that slow MongoDB operations are causing delays, you can check the performance of all in-progress operations by using the following methods:

• Enable the database profiler on your deployment. To learn more, see Database Profiler in the Server manual.

• Run the db.currentOp() MongoDB Shell command. To learn more, see the db.currentOp() documentation in the Server manual.

• Enable connection pool monitoring. To learn more, see Connection Pool Monitoring.

After you determine which operations are causing delays, try to improve the performance of these operations. Read the Best Practices Guide for MongoDB Performance for possible solutions.

If you implement performance best practices but still experience delays, you can modify your connection settings to increase the size of the connection pool. A connection pool is the group of connections to the server that the driver maintains at any time.

To specify the maximum size of a connection pool, you can set the maxPoolSize option in the connection options for your MongoClient instance. The default value of maxPoolSize is 100. If the number of in-use connections to a server reaches maxPoolSize, the next operation sent to the server pauses until a connection to the driver becomes available. The following code sets maxPoolSize to 150 when creating a new MongoClient:

const client = new MongoClient(uri, { maxPoolSize: 150 });

How Can I Ensure My Connection String Is Valid for a Replica Set?

The connection string passed to the driver must use exact hostnames for the servers as set in the Replica Set Config. Given the following configuration settings for your Replica Set, in order for the Replica Set discovery and failover to work the driver should be able to reach server1, server2, and server3.

{
  "_id": "testSet",
  "version": 1,
  "protocolVersion": 1,
  "members": [
    {
      "_id": 1,
      "host": "server1:31000"
    },
    {
      "_id": 2,
      "host": "server2:31001"
    },
    {
      "_id": 3,
      "host": "server3:31002"
    }
  ]
}

If you are unable to find the answer to your question here, try our forums and support channels listed in the Issues and Help section.