An API process may handle many requests while sharing one MongoDB client. The client manages database connections, but capacity and waiting still need a deliberate policy. This reference uses Node.js 24, MongoDB 8.0, and official mongodb driver 6.20.0. Create a disposable project, install mongodb@6.20.0, and save each complete program as an .mjs file. Set MONGODB_URI to its teaching database; the fallback names the isolated local port 27181. The main fixture issues concurrent reads through a small shared pool and checks observed checkout capacity. The practice owns a local non-MongoDB endpoint to demonstrate a server-selection failure, then verifies a separate healthy database client.
Reuse a client and size capacity per server
A MongoClient owns pools associated with servers in its selected topology. maxPoolSize limits application connections in a pool; it is not a universal cap on all network sockets opened by the process. Monitoring connections are additional, and multiple servers or multiple clients multiply the overall resource budget. The fixture uses directConnection to one teaching server so its checkout counter has one pool context. A real replica set deserves per-address monitoring rather than summing all checkouts and comparing that sum to one pool's maximum.
Create and reuse a client for the application lifecycle instead of constructing one for each request or database chunk. A larger pool does not make slow queries efficient, and an undersized pool can turn demand into waiting. Estimate concurrency from workload and service time, then measure wait and execution behavior. Multiple worker processes each own their clients, so deployment process count belongs in the capacity calculation. The six concurrent fixture reads illustrate bounded access; they do not justify choosing two connections for a production API.
Separate pool growth from queued application demand
maxConnecting limits how many new connections a pool establishes concurrently. It does not set the maximum number of operations that may be requested by application code, and it does not replace maxPoolSize. minPoolSize and idle-time settings influence warm capacity and unused connections. Driver version matters: the documented idle-connection behavior changed in driver 6.18, so this reference pins a later version rather than assuming every older driver behaves identically.
When no usable connection is immediately available, an operation can wait for checkout. waitQueueTimeoutMS bounds that wait under its configured contract. It does not prevent an application from allocating an unbounded number of promises or payload buffers before those operations reach the driver. Use application-level concurrency and admission limits as well. The fixture's Promise.all is bounded at six known reads. An import job with millions of records should instead use a bounded worker pattern and handle individual failures deliberately. Pool configuration is one layer of resource control, not a replacement for the rest of the application's queue design.
Identify which timeout boundary failed
serverSelectionTimeoutMS limits waiting to select an appropriate server. A reachable TCP socket is not necessarily a usable MongoDB server, as the practice demonstrates. connectTimeoutMS concerns establishing a connection, whereas socketTimeoutMS concerns inactivity during socket communication under its documented contract. waitQueueTimeoutMS concerns pool checkout. A query's maxTimeMS limits server execution where supported; it is not the same as a client-side queue deadline.
The driver also documents client-side operation timeout through timeoutMS, with rules for how its overall budget interacts with operations, retries, and cursors. Do not combine every timeout option mechanically or assume their numeric values simply add together. Read the pinned driver's interaction rules for the chosen API. Classify the observed failure and its phase before increasing a setting. A selection timeout can indicate unavailable topology; a checkout timeout can indicate saturated capacity; a server execution timeout can indicate expensive work. A timeout also does not automatically prove that a previously sent write had no effect. Recovery may require idempotency or checking the intended state.
Observe pools and close owned resources
Connection-pool monitoring events expose checkout and check-in boundaries as well as pool lifecycle changes. The main fixture increments its active count when a connection is checked out and decrements it when checked in. It checks the observed peak against the pool limit and prints only a boolean, because the exact peak can depend on scheduling and connection warm-up. A tiny fast workload should not promise that both connections must always be used.
Keep monitoring handlers short and avoid logging secrets or complete sensitive payloads. Production metrics should distinguish server addresses, failed checkout reasons, and meaningful latency distributions. During shutdown, stop accepting new work, await or cancel owned operations according to policy, close cursors and streams, and close the client at its ownership boundary. Closing a shared client after one request would interrupt other users of that client. Both complete fixtures use finally for cleanup. The practice also closes its owned TCP fixture so a failed selection does not leave a background listener or an unhandled retry loop behind.
MongoDB documentation and version notes
MongoDB Driver Pools and Timeouts Examples
Each example shows the code, the output it produces and what each part does.
Sharing a two-connection pool across concurrent reads
The complete program creates one shared client with a two-connection pool and a single concurrent connection-establishment limit. It resets a dedicated collection, inserts six records, and starts six reads. Monitoring counts checked-out application connections rather than all sockets. The output confirms every requested ID, an observed positive peak within the configured bound, and pool closure after the owning program finishes. It deliberately avoids claiming a precise connection count or timing benchmark. The cleanup happens even if a query or insertion throws.
import { MongoClient } from 'mongodb';
const client = new MongoClient(process.env.MONGODB_URI || 'mongodb://127.0.0.1:27181/?directConnection=true', {
maxPoolSize: 2, maxConnecting: 1, minPoolSize: 0,
waitQueueTimeoutMS: 2000, serverSelectionTimeoutMS: 2000
});
let active = 0, peak = 0, closed = false;
client.on('connectionCheckedOut', () => { active++; peak = Math.max(peak, active); });
client.on('connectionCheckedIn', () => { active--; });
client.on('connectionPoolClosed', () => { closed = true; });
try {
await client.connect();
const records = client.db('codevra_ref_pools').collection('records');
await records.deleteMany({});
await records.insertMany(Array.from({ length: 6 }, (_, i) => ({ _id: i + 1, value: i + 1 })));
const result = await Promise.all(Array.from({ length: 6 }, (_, i) => records.findOne({ _id: i + 1 })));
console.log('IDs: ' + result.map(d => d._id).join(','));
console.log('pool bounded: ' + (peak > 0 && peak <= 2 && active === 0));
} finally { await client.close(); }
console.log('pool closed: ' + closed);IDs: 1,2,3,4,5,6
pool bounded: true
pool closed: trueMongoDB Driver Pools and Timeouts in Real Projects
Trigger a server selection timeout on a fake endpoint
Show that accepting TCP connections is insufficient for selecting a MongoDB server. The program binds an owned loopback endpoint on an automatically chosen free port. It immediately destroys accepted sockets instead of speaking the MongoDB protocol. A driver client therefore reaches its short server-selection limit and raises MongoServerSelectionError. The code catches only that expected failure, then cleans up both client and listener. Finally a new client pings the real teaching MongoDB server successfully. No existing local service or user database is probed to create the failure; the deliberately broken endpoint belongs to this fixture.
import { MongoClient } from 'mongodb';
import net from 'node:net';
const endpoint = net.createServer(socket => socket.destroy());
await new Promise((resolve, reject) => { endpoint.once('error', reject); endpoint.listen(0, '127.0.0.1', resolve); });
const port = endpoint.address().port;
const broken = new MongoClient('mongodb://127.0.0.1:' + port + '/?directConnection=true', {
serverSelectionTimeoutMS: 250, connectTimeoutMS: 50, maxPoolSize: 1
});
try {
await broken.connect();
throw new Error('A non-MongoDB endpoint unexpectedly connected');
} catch (error) {
if (error.name !== 'MongoServerSelectionError') throw error;
console.log('failure: ' + error.name);
} finally {
await broken.close();
await new Promise((resolve, reject) => endpoint.close(error => error ? reject(error) : resolve()));
}
const healthy = new MongoClient(process.env.MONGODB_URI || 'mongodb://127.0.0.1:27181/?directConnection=true', { serverSelectionTimeoutMS: 2000 });
try {
await healthy.connect();
const result = await healthy.db('codevra_ref_pools').command({ ping: 1 });
console.log('healthy ping: ' + result.ok);
} finally { await healthy.close(); }failure: MongoServerSelectionError
healthy ping: 1MongoDB Driver Pools and Timeouts FAQ
Is maxPoolSize the total socket count for my application?
No. It applies to a pool's application connections, while monitoring connections and additional server pools contribute other sockets. Multiple MongoClient instances and worker processes multiply that budget. The one-server fixture can compare its aggregate checkout count to two because its topology is deliberately restricted. A production topology should track counts by server and client ownership.
Does maxConnecting limit concurrent queries to one here?
No. It bounds simultaneous connection establishment. Once connections exist, their checkout capacity is governed by the pool and the workload. The application can still request six reads concurrently, as the fixture does. Treat startup growth, established pool capacity, and pending application demand as separate quantities when diagnosing latency or connection bursts.
Can waitQueueTimeoutMS prevent an unbounded import queue?
It bounds a particular driver's checkout wait, not every upstream promise, payload, or job record. A caller can allocate far too much work before the driver applies that boundary. Add a bounded application worker queue and a clear rejection or retry policy. Pool waiting limits help fail saturated work but do not provide complete admission control for the application.
Should I retry every operation after a timeout?
No. Determine which boundary failed and whether the operation may have reached the server. A write can have an uncertain outcome, so blindly repeating a non-idempotent effect can be incorrect. Use the driver's documented retry behavior, idempotent operations, or state verification as appropriate. Increasing a timeout without identifying selection, checkout, or execution pressure can hide rather than resolve the cause.
MongoDB Driver Pools and Timeouts Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
Why can the practice raise MongoServerSelectionError despite its TCP listener accepting connections?
MongoDB Driver Pools and Timeouts Quiz
2 questions to check what you learned.
Which option limits waiting for a pooled connection checkout?
- waitQueueTimeoutMS
- maxConnecting
- maxTimeMS
What does the main fixture establish about observed pool use?
- The positive checkout peak stays within two and all six reads complete
- Exactly two sockets exist in the whole process
- The six reads run as one atomic transaction