Google Spanner runs distributed transactions across a globally replicated database at scale. It can’t afford to block on coordinator failure. Its solution is to not use a standalone coordinator at all – it runs 2PC on top of Paxos groups, which means the coordinator itself is fault-tolerant.

The Core Move: Paxos Groups as Participants

In classic 2PC, each participant is a single node. It votes, acquires locks, and waits. If it crashes, the transaction is stuck.

Spanner’s participants are Paxos groups. Each shard of data is managed by a Paxos group – typically 5 replicas spread across datacenters. The Paxos leader for each group acts as the 2PC participant. Lock acquisition and voting happen on the leader, and the decision is durably replicated to the group before the leader responds.

If the coordinator crashes, a new coordinator can be elected (it’s also a Paxos group). If a participant leader crashes, a new leader in that group takes over – the lock state and vote are already replicated, so the protocol can continue.

The blocking problem is solved not by changing the protocol but by making every node in the protocol fault-tolerant.

TrueTime

Spanner adds something 2PC doesn’t have: globally synchronized timestamps, accurate enough to use for transaction ordering.

Google runs GPS receivers and atomic clocks in each datacenter and exposes a TrueTime API that returns a time interval [earliest, latest] rather than a single timestamp. The interval accounts for clock uncertainty. The guarantee is that the real current time lies somewhere in that interval.

Spanner uses TrueTime to assign commit timestamps. The rule: a transaction’s commit timestamp must be after the latest bound of TrueTime at the moment the coordinator decides to commit. This means Spanner waits for a brief period – typically 1-7ms – before declaring a transaction committed, to ensure that any other transaction starting after this one will see a strictly later timestamp.

This is the “commit wait.” It’s intentional latency, paid to guarantee that commit timestamps accurately reflect real-world ordering.

External Consistency

The property this buys is external consistency: if transaction T1 commits before T2 starts (in real-world time), T2 will see T1’s writes. This is stronger than serializability – serializable transactions can be ordered in any way consistent with their conflicts, even if that reorders real-world causality. External consistency preserves real-world order.

In practical terms: if you commit a write and then tell a colleague “it’s committed, go read it,” their read will see your write. There’s no window where a causally later transaction misses a causally earlier committed write.

Most distributed databases don’t provide this. They provide serializability, which is strong, but allows committed writes to be temporarily invisible to transactions that started after the commit in real time. Spanner’s external consistency closes that gap.

What the 2PC Layer Actually Looks Like

A read-write transaction in Spanner:

1. Client reads data, buffers writes locally (no locks yet)
2. Client sends commit request to the coordinator Paxos group
3. Coordinator runs 2PC with each participant Paxos group:
   • Sends PREPARE to each participant leader
   • Each participant leader acquires locks, logs the prepare record to its Paxos group, replies YES
   • Coordinator picks a commit timestamp (TrueTime latest + epsilon), logs it to its group
   • Sends COMMIT with the timestamp to all participants
4. Coordinator waits out the commit wait interval
5. Participants apply the writes at the commit timestamp, release locks
6. Client sees commit confirmation

The 2PC messages are still there. The key difference is that every step that touches durable state goes through a Paxos replication round first. The coordinator can crash and be replaced. A participant leader can crash and its successor has the full prepare state. Nothing blocks permanently.

The Cost

The commit wait adds latency. For single-region transactions it’s small (sub-millisecond when clocks are well-synchronized). For multi-region transactions where the coordinator and participants are in different continents, round-trip latency dominates and the TrueTime uncertainty is larger – you’re looking at tens of milliseconds.

Spanner is designed for this tradeoff: strong global consistency in exchange for latency that scales with geographic distance. For financial systems, global inventory, or anything that requires real external consistency, that tradeoff is often correct. For low-latency local transactions, it’s usually not.

Classic 2PC is blocking because the coordinator is a single node. Spanner’s answer is not to fix 2PC – it’s to make every node in the 2PC protocol a replicated state machine.

The outbox pattern closes that gap.

The Dual-Write Problem

Say the flight reservation step succeeds. You update your database to mark the reservation as confirmed and then publish a FlightReserved event to your message broker. These are two operations against two different systems. There’s no way to make them atomic without 2PC – which is exactly what sagas are trying to avoid.

If you write to the database first and then crash before publishing, the event is never delivered. The hotel reservation step never starts. The saga stalls. Depending on your monitoring, this might sit undetected for a while.

If you publish first and then crash before writing to the database, you’ve told the hotel step to proceed even though the flight reservation isn’t durably recorded. The flight service comes back up with no record of the reservation. You’ve introduced a phantom.

The Outbox

The fix: write the event to an outbox table in the same database, in the same local transaction as your state update. Then have a separate process relay events from the outbox to the message broker.

BEGIN TRANSACTION
  UPDATE flights SET status = 'reserved' WHERE id = ?
  INSERT INTO outbox (event_type, payload, created_at)
    VALUES ('FlightReserved', '{"booking_id": 123, ...}', NOW())
COMMIT

The state change and the event are now atomic with respect to the database. Either both are committed or neither is. The outbox row is durable.

A separate relay process – sometimes called the outbox processor or message relay – polls the outbox table, publishes each event to the message broker, and marks the row as processed once delivery is confirmed.

Relay process:
  SELECT * FROM outbox WHERE processed_at IS NULL ORDER BY created_at LIMIT 100
  FOR EACH row:
    publish to message broker
    UPDATE outbox SET processed_at = NOW() WHERE id = row.id

At-Least-Once Delivery

The relay delivers at-least-once. If the relay crashes after publishing but before marking the row as processed, it will publish the same event again on restart. Downstream consumers have to be idempotent – processing the same event twice should produce the same result as processing it once.

This is a real design constraint. Your hotel reservation step needs to check whether it already processed a given FlightReserved event before creating a new reservation. Deduplication is typically done with a unique constraint on the event ID or booking ID in the receiving service’s database.

At-least-once with idempotent consumers is the standard contract in event-driven systems. Exactly-once is theoretically possible with additional coordination but practically rare – most systems accept at-least-once and invest in idempotency instead.

Change Data Capture as an Alternative Relay

Polling the outbox table works but adds load to the database. An alternative is Change Data Capture (CDC): instead of a polling process, you read directly from the database replication log.

Tools like Debezium connect to PostgreSQL’s logical replication stream or MySQL’s binlog and emit a change event for every row insert. Point Debezium at the outbox table and it publishes events automatically, with no polling query needed.

CDC-based relay has lower overhead and lower latency. The tradeoff: it’s another piece of infrastructure to run and operate. For smaller deployments, polling is simpler. For high-throughput systems where polling lag or database load is a concern, CDC is worth it.

Saga State Persistence

Related to the outbox is the question of where saga state itself lives.

The orchestrator driving the saga needs to know the current step, which steps have completed, and what the compensating actions are if something fails. Two common approaches:

Dedicated saga store: the orchestrator writes saga state to its own database table after each step. Simple, queryable, easy to inspect when debugging a stuck saga. The outbox pattern applies here too – saga state update and event publish happen in the same transaction.

Event sourcing: saga state is derived from the event log itself. There’s no explicit state table – you reconstruct the saga’s current position by replaying events. More complex to implement but gives you a full audit trail of everything that happened and an easy path to replaying failed sagas.

Most teams start with a dedicated saga store and move to event sourcing only if they need the audit trail or replay capability.

What Fails in Compensation

One more gap worth naming: compensating transactions can fail too.

You cancel the hotel reservation as part of rolling back a failed booking. The cancel call times out. Now your saga is stuck in a partially compensated state – the flight is cancelled but the hotel reservation is still live.

The standard answer is retry with backoff. Compensating transactions need to be idempotent for the same reason forward steps do. The outbox pattern helps here too – compensation requests go through the same outbox mechanism, so they’re durably enqueued even if the downstream service is temporarily unavailable.

If compensation keeps failing after retries, the saga is in a “saga failure” state that requires human intervention or a dead-letter queue. Building an operator UI for stuck sagas is not glamorous work, but it’s necessary in any production saga implementation.

The outbox pattern doesn’t make sagas simple. It removes the dual-write problem and gives you reliable event delivery – which turns a fundamentally broken approach into one that’s merely complex.

When N changes to N+1 or N-1, nearly every key remaps to a different node. You go from a warm cache to a cold one in an instant – a thundering herd of cache misses hitting your database all at once. For a large cluster, that’s enough to take down a service.

Consistent hashing fixes this. Add or remove a node, and only the keys that were assigned to that node need to move. Everything else stays put.

The Hash Ring

Instead of hash(key) % N, arrange all possible hash values on a ring from 0 to 2^32. Each node gets a position on the ring by hashing its name or ID. To find which node owns a key: hash the key, then walk clockwise around the ring until you hit a node.

          0
         / \
    Node C   Node A
       |         |
    Node B --- Node D

Key K hashes to a point on the ring. The first node clockwise from that point owns K.

Now add a new node between B and C. Only the keys that were between B and the new node’s position need to move – from C to the new node. Everything else is unaffected. In an N-node cluster, adding one node moves roughly 1/N of the keys instead of nearly all of them.

Virtual Nodes

Raw consistent hashing has a load distribution problem. With a small number of physical nodes, the gaps between them on the ring are uneven – one node might own 30% of the keyspace, another 10%. Remove a node and all its load lands on a single neighbor.

Virtual nodes fix this: each physical node gets multiple positions on the ring, typically by hashing it with different suffixes (node1-0, node1-1, node1-2, …). With enough virtual nodes per physical node, the load distributes evenly across the ring. Removing one node scatters its keys across many neighbors rather than dumping them all on one.

This is the production configuration in every serious deployment.

Where It’s Used

• Amazon DynamoDB – consistent hashing across storage nodes, virtual nodes for even distribution
• Apache Cassandra – the token ring is consistent hashing; each node owns a range of tokens
• Memcached – the ketama client implements consistent hashing for cache node assignment
• Basically every distributed cache or storage system that needs to scale nodes without full reshuffling

The pattern generalizes beyond caching. Any system that needs to assign work or data to nodes – and occasionally add or remove nodes – runs into the same problem. Consistent hashing is the standard solution.

Two-phase commit (2PC) solves this. It’s been in production databases for decades. It also has a flaw that makes it unusable for anything long-running, which is why most modern large-scale systems don’t use it directly.

The Protocol

There’s a coordinator and a set of participants. The coordinator drives the protocol.

Phase 1 – Prepare

The coordinator sends PREPARE to every participant. Each participant:

• Writes the transaction to a durable log
• Acquires the necessary locks
• Replies YES (ready to commit) or NO (something failed)

Phase 2 – Commit or Abort

• If all participants said YES: coordinator sends COMMIT to everyone
• If anyone said NO: coordinator sends ABORT

Participants execute the decision and release their locks.

Coordinator         Node A        Node B
    |--- PREPARE ------->|             |
    |--- PREPARE ---------|----------->|
    |<-- YES ------------|             |
    |<-- YES ------------|-------------|
    |--- COMMIT -------->|             |
    |--- COMMIT ----------|----------->|

Clean path works fine. Every node ends up in the same state. Locks are held only for the duration of the protocol.

The Fatal Flaw

Crash the coordinator after phase 1 but before phase 2.

Participants are now stuck. They voted YES and locked their resources. They don’t know whether the coordinator decided to commit or abort. They can’t safely proceed in either direction – committing might be wrong if another participant said NO, aborting might be wrong if the coordinator was about to send COMMIT.

They wait. The locks stay held. The system is in limbo until the coordinator recovers.

This is the blocking problem. 2PC is a blocking protocol under failure. A single coordinator crash can stall the entire transaction indefinitely.

The Attempted Fix: 3PC

Three-phase commit inserts a pre-commit phase between prepare and commit:

PREPARE → PRE-COMMIT → COMMIT

Pre-commit lets participants infer the coordinator’s intent even if it crashes: if you received a pre-commit, the coordinator had seen all YES votes and was going to commit. You can safely commit yourself if the coordinator disappears after that point.

3PC eliminates most blocking scenarios. It costs one extra round of messages and still has edge cases under network partitions. It’s not widely used in practice – the complexity tradeoff isn’t worth it for most systems.

What Systems Actually Do

Most large-scale systems avoid 2PC for anything user-facing. Short, internal database transactions – a single service committing to one database – are fine. Cross-service transactions that could run for seconds or involve user interaction are not.

2PC is worth understanding because it makes the tradeoff concrete: you can have distributed atomicity, but you’re paying for it with availability under coordinator failure. Everything else in distributed transactions is a different point on that curve.

Why increasing maxPoolSize breaks your database. A deep dive into MongoDB connection pooling, SDAM, WiredTiger tickets, and preventing transaction pinning.

Introduction

In the MongoDB ecosystem, the “connection pool” is often treated as a set-and-forget configuration within MongoClient. However, when latency spikes or the database becomes unresponsive during high traffic, the pool is usually the first mechanism to break.

Unlike relational databases that often sit behind proxies like PgBouncer, MongoDB drivers are “smart”—they maintain direct connections to multiple nodes in a Replica Set or Sharded Cluster. This complexity means exhaustion isn’t just about running out of sockets; it’s about topology monitoring, transaction pinning, and the brutal reality of the thread-per-connection model on the server side.

How MongoDB Connects and Executes Queries

Before diving into pool exhaustion, it’s worth understanding the lifecycle of a MongoDB connection and query. The process is more involved than a simple socket open/close.

Connection Establishment

When your application calls MongoClient.connect(), the driver doesn’t immediately open a socket. Instead, it:

1. TCP Socket Creation: Establishes a TCP/IP connection to the MongoDB server (default port 27017). This is a standard three-way handshake at the network layer.

2. Wire Protocol Handshake: The client sends a hello command (formerly isMaster in older versions) to the server. This serves multiple purposes:

   • Verifies the server is a MongoDB instance
   • Retrieves server capabilities (wire protocol version, supported authentication mechanisms)
   • In MongoDB 4.4+, can include speculativeAuthenticate to start authentication concurrently, reducing latency

3. Authentication: If credentials are provided, the client authenticates using mechanisms like SCRAM (Salted Challenge Response Authentication Mechanism):

   • Client sends saslStart with chosen mechanism and initial payload
   • Server responds with a challenge
   • Client computes and sends proof derived from the challenge
   • Server verifies and grants access

This entire process—TCP handshake, TLS negotiation (if enabled), handshake, and authentication—typically takes 10-50ms depending on network latency and encryption overhead.

Query Execution Flow

Once authenticated, the connection is ready for operations. When you execute a query:

1. Connection Checkout: The driver checks out a connection from the pool (or waits if none are available—this is where exhaustion manifests).

2. Message Construction: The query is serialized into MongoDB’s wire protocol format. Modern MongoDB uses the OP_MSG opcode (introduced in 3.6), which includes:

   • Standard message header (request ID, response-to ID)
   • Flags indicating message properties
   • Sections containing the actual command/query data
   • Optional checksum for integrity

3. Network Transmission: The message is sent over the TCP socket to the server.

4. Server Processing: The mongod process:

   • Receives the message on a dedicated thread (in the thread-per-connection model)
   • Parses the query
   • Plans execution strategy
   • Accesses data through WiredTiger (subject to ticket limits)
   • Creates a cursor for read operations

5. Response: The server sends results back over the same connection. For large result sets, the driver uses cursors to fetch documents in batches (default batch size is 101 documents).

6. Connection Return: After the operation completes, the connection is returned to the pool for reuse—unless it’s pinned to a transaction (see “The Specific Pathology: Pinning” below).

Why This Matters for Pooling

Each of these steps has latency and resource costs. The connection establishment overhead (10-50ms) is why pooling exists: reusing connections avoids paying this cost for every operation. However, the server-side thread allocation means each connection has a real memory and scheduling cost on mongod, which is why blindly increasing pool size backfires.

Connection Pool Internals

Understanding how the pool manages connections internally is crucial for diagnosing exhaustion. The pool maintains connections in different states:

Connection States

1. Idle: Connections that are established and authenticated but not currently in use. These sit in the pool, ready for immediate checkout. They consume server-side resources (thread + memory) but are available for operations.

2. Checked Out: Connections actively executing an operation. When you call collection.find(), the driver checks out a connection, performs the operation, then returns it to idle—unless it’s pinned (see “The Specific Pathology: Pinning”).

3. Pending: Connections in the process of being established (TCP handshake, authentication). These don’t count toward maxPoolSize until fully established.

4. Closed: Connections that have been terminated, either due to errors, idle timeout, or explicit closure.

The Wait Queue

When all connections are checked out and the pool has reached maxPoolSize, new requests enter a wait queue. This queue has its own limits:

• waitQueueTimeoutMS: How long a request waits for a connection before throwing ConnectionPoolCheckoutFailed. Default is 0 (infinite wait—dangerous in production). Always set this to fail fast rather than hang indefinitely.

If the wait queue fills up, your application starts failing requests. This is often the first symptom of pool exhaustion, not the root cause.

Connection Lifecycle

The connection lifecycle follows these states and transitions:

[Not Created]
    │
    │ connect()
    ▼
[Pending] ── TCP handshake, authentication ──► [Idle]
    │                                              │
    │                                              │ Driver request
    │                                              ▼
    │                                        [Checked Out]
    │                                              │
    │                                              │ Operation complete
    │                                              │
    │                                              ▼
    │                                          [Idle] ◄──┐
    │                                              │     │
    │                                              │     │ Return to pool
    │                                              │     │
    │                                              │     │
    │                                              │ startTransaction()
    │                                              ▼     │
    │                                          [Pinned] ──┘
    │                                              │
    │                                              │ ʕ•ᴥ•ʔ DANGEROUS:
    │                                              │ Exclusive to session
    │                                              │ until commit/abort
    │                                              │
    │                                              │ commit/abortTransaction()
    │                                              ▼
    │                                          [Idle]
    │                                              │
    │                                              │ maxIdleTimeMS reached
    │                                              ▼
    │                                          [Closed]
    │                                              │
    └──────────────────────────────────────────────┘

State Descriptions:

• Pending: Connection is being established (TCP handshake, authentication)
• Idle: Connection is established and available in the pool for immediate use
• Checked Out: Connection is actively executing an operation
• Pinned: Connection is reserved for a transaction (removed from pool until transaction completes)
• Closed: Connection has been terminated

The pool lazily creates connections up to maxPoolSize. If minPoolSize > 0, it pre-warms that many connections at startup. Connections idle longer than maxIdleTimeMS are closed to free server resources.

SDAM: The Hidden Connection Overhead

MongoDB drivers implement SDAM (Server Discovery and Monitoring), which maintains connections to all nodes in a Replica Set or Sharded Cluster, not just the primary.

How SDAM Works

1. Initial Discovery: On MongoClient.connect(), the driver connects to seed addresses and sends hello commands to discover all replica set members.

2. Continuous Monitoring: Every heartbeatFrequencyMS (default 10 seconds), the driver sends hello to each known node to:

   • Detect role changes (primary elections, step-downs)
   • Check server capabilities
   • Update topology description

3. Topology Events: When a primary election occurs, the driver:

   • Closes connections to the old primary
   • Opens connections to the new primary
   • Potentially drains and recreates pools

The Connection Multiplier

If you have a 3-node replica set and set maxPoolSize=50, you’re not creating 50 connections—you’re creating up to 150 connections (50 per node). SDAM maintains separate pools for each server in the topology.

During a primary election, the driver may temporarily exceed this as it transitions between nodes. If you’re running 20 app instances, that’s 3,000 potential connections during failover, even if only one node is serving traffic.

Takeaway: Your maxPoolSize is per-server, not per-client. In replica sets, multiply by the number of nodes you’re monitoring.

Connection Pool Configuration Options

Here are the key options that affect pool behavior:

• maxPoolSize: Maximum connections per server. Default 100. This is the most commonly misconfigured setting.

• minPoolSize: Minimum idle connections to maintain. Default 0. Setting this > 0 pre-warms the pool but consumes server resources even when idle.

• maxIdleTimeMS: Close idle connections after this duration. Default 0 (never close). Useful in serverless where you want aggressive cleanup.

• waitQueueTimeoutMS: How long to wait for a connection before failing. Default 0 (wait forever—dangerous in production). Always set this to fail fast rather than hang indefinitely.

• connectTimeoutMS: Timeout for initial connection establishment. Default 30 seconds.

• socketTimeoutMS: Timeout for individual operations. Default 0 (no timeout). Different from connection checkout timeout.

• heartbeatFrequencyMS: How often SDAM checks server status. Default 10 seconds. Lower values detect failovers faster but increase network overhead.

• TCP Keepalive: Often overlooked. If your app sits behind a firewall or load balancer (e.g., AWS Network Load Balancer) with a 350s idle timeout, and your pool has maxIdleTimeMS > 350s, the LB will silently drop the connection. The driver won’t know until it tries to write to the socket and fails. Important: socketTimeoutMS does not send keepalive probes. Best Practice: Set maxIdleTimeMS to be slightly lower than your infrastructure’s timeout (e.g., 120000ms). On Linux, also tune net.ipv4.tcp_keepalive_time to be less than the cloud provider’s timeout (usually < 120 seconds).

Example Configuration (Node.js):

1const client = new MongoClient(uri, {
2  maxPoolSize: 10,              // Small pool for 16-core DB
3  minPoolSize: 2,               // Pre-warm 2 connections
4  maxIdleTimeMS: 30000,         // Close idle after 30s
5  waitQueueTimeoutMS: 5000,     // Fail after 5s wait
6  connectTimeoutMS: 10000,      // 10s connection timeout
7  socketTimeoutMS: 45000,       // 45s operation timeout
8  heartbeatFrequencyMS: 10000   // Check every 10s
9});

The Cost of a Connection in mongod

While MongoDB has moved toward a more asynchronous networking model in recent versions, historically (and effectively, for resource planning), it relies on a synchronous thread-per-connection model.

When your application opens a new connection:

1. Network: TCP handshake + TLS negotiation (CPU intensive).
2. Authentication: SCRAM or X.509 handshakes occur.
3. Memory: The mongod process allocates stack memory (typically ~1MB) for the thread handling that connection.
4. Context: The internal serviceExecutor must schedule this thread.

If you set maxPoolSize=100 on 50 Kubernetes pods, you are allowing 5,000 potential concurrent threads on the Primary. Before you hit hardware limits, you will likely hit WiredTiger ticket exhaustion.

The Math: Sizing for WiredTiger

The naive approach is to increase maxPoolSize when you see ConnectionPoolCheckoutFailed errors. This is usually wrong.

WiredTiger (the storage engine) uses “tickets” to control concurrency. In MongoDB versions prior to 7.0, there are 128 read tickets and 128 write tickets by default. MongoDB 7.0+ uses dynamic ticketing that adjusts based on workload, but still caps at 128 per type. Note on MongoDB 7.0+: While the hard cap remains 128 tickets, the dynamic algorithm often lowers this limit (e.g., to 60 or 80) in real-time to preserve latency. This means you might see queuing before you hit 128 concurrent active queries. If 1,000 connections try to read simultaneously, 872 of them are just queuing inside the kernel, consuming RAM but doing zero work.

The optimal pool size formula remains tied to hardware capability, not traffic volume:

If your database has 16 cores and you have 20 application instances, a maxPoolSize of 100 is overkill. You might actually achieve higher throughput with a pool size of 2 or 3 per instance, preventing the database from spending all its cycles on context switching.

Note: The (Cores * 2) rule applies strictly to the active executing threads. You can have a larger pool to handle network jitter, but waitQueueTimeoutMS is your safety valve. If you need 100 connections to saturate the CPU, your queries are likely too slow (unindexed). Fix the queries, don’t inflate the pool.

Workload Considerations:

• CPU-Bound Workloads: The formula above applies directly. Each active connection should map to an executing thread.
• IO-Bound Workloads: If the working set doesn’t fit in RAM and disk I/O is the bottleneck, a slightly larger pool might help hide I/O latency, though typically minPoolSize is more relevant here to avoid establishing connections during I/O spikes.
• Atlas Proxy / Serverless: If using MongoDB Atlas Serverless or the Atlas Proxy, the connection limits are handled differently (via a proxy layer), and the “100 limit” on the client side is less about server stress and more about client-side throttling.

The Specific Pathology: “Pinning”

Since you are versed in Mongo, you know the drivers implement the SDAM (Server Discovery and Monitoring) specification. But the most dangerous feature regarding pooling is Client-Side Operation Pinning, specifically with Transactions.

In a standard read/write, the driver grabs a connection, executes, and returns it. In a Transaction (Multi-Document ACID):

1. session.startTransaction() is called.
2. The driver pins a connection to that session.
3. That connection is removed from the pool and reserved exclusively for this session until commitTransaction or abortTransaction is called.

The Exhaustion Scenario

If you have maxPoolSize=50 and an API endpoint that takes 2 seconds to execute some logic inside a transaction, you can only serve 25 requests per second. The 26th request will wait. If the logic hangs (e.g., waiting for a third-party HTTP call), you will drain the pool instantly, causing a cascading failure across the app.

ʕ•ᴥ•ʔ Critical Rule: Never perform network I/O or long computations inside a MongoDB transaction. Transactions should be atomic, fast, and only contain database operations.

Practical Examples: The Right Way vs. The Wrong Way

Proper Client Initialization

Node.js - Express (Correct):

 1// app.js - Initialize once at startup
 2const { MongoClient } = require('mongodb');
 3
 4let client;
 5let db;
 6
 7async function initDatabase() {
 8  client = new MongoClient(uri, {
 9    maxPoolSize: 10,
10    waitQueueTimeoutMS: 5000
11  });
12  await client.connect();
13  db = client.db('myapp');
14  console.log('Database connected');
15}
16
17// Initialize before starting server
18initDatabase().then(() => {
19  app.listen(3000);
20});
21
22// Use the same client instance everywhere
23app.get('/users', async (req, res) => {
24  const users = await db.collection('users').find({}).toArray();
25  res.json(users);
26});

Node.js - Express (Wrong - Creates New Pool Per Request):

1// ʕ•̀ω•́ʔ DON'T DO THIS
2app.get('/users', async (req, res) => {
3  const client = new MongoClient(uri);  // New pool every request!
4  await client.connect();
5  const db = client.db('myapp');
6  const users = await db.collection('users').find({}).toArray();
7  await client.close();  // Closes pool, but too late
8  res.json(users);
9});

Python - Gunicorn (Correct):

 1# app.py - Create client after fork
 2from pymongo import MongoClient
 3
 4client = None
 5db = None
 6
 7def on_starting(server):
 8    # This runs in the master process
 9    pass
10
11def when_ready(server):
12    # This runs in each worker after fork
13    global client, db
14    client = MongoClient(uri, maxPoolSize=10)
15    db = client['myapp']
16
17@app.route('/users')
18def get_users():
19    users = list(db.users.find({}))
20    return jsonify(users)

Python - Gunicorn (Wrong - Fork-Unsafe):

 1# ʕ•̀ω•́ʔ DON'T DO THIS
 2from pymongo import MongoClient
 3
 4# Created in master process - NOT fork-safe!
 5client = MongoClient(uri)
 6db = client['myapp']
 7
 8@app.route('/users')
 9def get_users():
10    # Child processes share parent's file descriptors = deadlocks
11    # This often results in AutoReconnect errors or 
12    # 'file descriptor bad' errors because the socket 
13    # is shared across memory boundaries
14    users = list(db.users.find({}))
15    return jsonify(users)

Java - Spring Boot:

 1spring:
 2  data:
 3    mongodb:
 4      uri: "mongodb://user:pass@host1:27017,host2:27017/?replicaSet=myRS&maxPoolSize=10&minPoolSize=2&maxIdleTimeMS=30000"
 5
 6// Or if using a Configurer Bean (safe way to customize without breaking auto-config)
 7@Configuration
 8public class MongoConfig {
 9    @Bean
10    public MongoClientSettingsBuilderCustomizer customizer() {
11        return builder -> builder.applyToConnectionPoolSettings(pool -> {
12            pool.maxSize(10);
13            pool.maxWaitTime(5, TimeUnit.SECONDS);
14        });
15    }
16}

The Health Check Trap:

ʕ•ᴥ•ʔ Warning: Do not create a new MongoClient inside your Kubernetes readiness/liveness probe. This is a classic DOS attack on your own database. The probe runs every 10s; if it creates a new connection each time without proper closure, you will exhaust the server limits in minutes. Use the singleton client to run a lightweight command like db.command({ ping: 1 }).

Monitoring Pool Metrics

Node.js - Command Monitoring:

 1const { MongoClient } = require('mongodb');
 2
 3const client = new MongoClient(uri, {
 4  monitorCommands: true  // Enable command monitoring
 5});
 6
 7client.on('commandStarted', (event) => {
 8  console.log('Command:', event.commandName);
 9});
10
11client.on('commandSucceeded', (event) => {
12  console.log('Duration:', event.duration, 'ms');
13});
14
15// For connection pool metrics, use pool monitoring events
16client.on('connectionCheckedOut', (event) => {
17  if (event.duration > 100) {  // Checkout took > 100ms
18    console.warn('Slow connection checkout:', event.duration, 'ms');
19  }
20});
21
22client.on('commandFailed', (event) => {
23  if (event.error.code === 'ConnectionPoolCheckoutFailed') {
24    console.error('Pool exhausted!');
25  }
26});

Go - Pool Monitoring:

 1import (
 2    "go.mongodb.org/mongo-driver/event"
 3    "go.mongodb.org/mongo-driver/mongo"
 4)
 5
 6poolMonitor := &event.PoolMonitor{
 7    Event: func(evt *event.PoolEvent) {
 8        switch evt.Type {
 9        case event.ConnectionCreated:
10            fmt.Println("Connection created")
11        case event.ConnectionCheckedOut:
12            fmt.Println("Connection checked out")
13        case event.ConnectionCheckoutFailed:
14            fmt.Println("Checkout failed:", evt.Reason)
15        case event.ConnectionReturned:
16            fmt.Println("Connection returned")
17        }
18    },
19}
20
21clientOptions := options.Client().
22    ApplyURI(uri).
23    SetPoolMonitor(poolMonitor).
24    SetMaxPoolSize(10)
25
26client, _ := mongo.Connect(context.TODO(), clientOptions)

Driver Nuances & Pitfalls

Node.js (Mongoose / Native Driver)

The Node driver is asynchronous, but the pool logic is strict.

• The Singleton Mistake: A common pattern in serverless or improper Express setup is calling MongoClient.connect() inside the route handler. This creates a new pool for every request, rapidly hitting the Atlas connection limit (e.g., 1,500 connections on M10). Always initialize the client once at startup.
• Unified Topology: The Node.js driver (v4.0+) uses Unified Topology by default (it’s the only option). This keeps a background monitoring thread that can detect step-downs. If your pool churns during a primary election, check if your heartbeatFrequencyMS is tuned correctly.

Python (PyMongo)

• Fork Safety: MongoClient is not fork-safe. If you use gunicorn or uwsgi with forking, you must create the client after the fork (e.g., inside the worker process initialization), or you will end up with child processes trying to use the parent’s file descriptors, leading to deadlocks and obscure socket errors. This often manifests as AutoReconnect errors or “file descriptor bad” errors.
• Wait Queue: In PyMongo 4.0+, waitQueueMultiple was removed. Use waitQueueTimeoutMS to control how long threads wait for connections. Limit your application’s thread pool size to control concurrency.

Java (Spring Boot / MongoDB Java Driver)

• Automatic Pooling: The MongoTemplate handles pooling automatically. Ensure spring.data.mongodb.database settings do not override defaults with aggressive timeouts. The Java driver’s default maxPoolSize is 100, which is often too high for production.

Go (mongo-go-driver)

• The Go driver respects context. If your Connect or Find context times out, the connection might be closed or returned to the pool depending on the stage.
• Monitor PoolEvent via the SetPoolMonitor option to visualize exactly when connections are created vs. checked out.

Serverless & Atlas Implications

In MongoDB Atlas, connection limits are hard tiers.

• M0 (Free Tier): 500 connections per node
• M10: 1,500 connections per node
• M20: 3,000 connections per node
• Serverless Instances: These bill by “Read Processing Units” but still require connection management.

If you are running on AWS Lambda or Vercel, you cannot maintain a persistent pool. Every “warm” container might keep a pool of 10 open. 100 concurrent Lambdas = 1,000 connections. Solution: You typically cannot use standard pooling here. You must aggressively close connections (set maxIdleTimeMS very low) or use the Atlas Data API (HTTP based) instead of the TCP driver to avoid socket exhaustion.

Monitoring & Diagnosis

How do you know it’s a pool issue and not a slow query?

1. Check the Server:

   1db.serverStatus().connections
   2// look for { "current": 1200, "available": 50 }
   

   If current is high, your app is leaking connections or scaling too wide.

2. Check the Queue: Monitor WiredTiger ticket usage via db.serverStatus().wiredTiger.concurrentTransactions or connection counts. If active connections significantly exceed your pool size or WiredTiger tickets are exhausted, your latency is due to queuing, not network speed.

3. Zombie Connections: When a client crashes hard (OOM Kill) without sending a TCP FIN, the server keeps the connection open until the server-side tcp_keepalive times out. In high-churn Kubernetes environments, this can exhaust the server’s file descriptors even if the active pool count seems low. This reinforces the need for aggressive maxIdleTimeMS and proper TCP keepalive configuration.

4. Driver Metrics: Enable command monitoring in your driver. If connectionCheckoutTime spikes while commandDuration (server execution time) stays low, the problem is client-side exhaustion. The database is fast; the line to get to it is slow.

5. Connection Churn Rate: Monitor the rate of new connections (connectionsCreated per second). If this is high (>10/sec per node) while your total pool count is stable, your maxIdleTimeMS is likely too low. You are burning server CPU on SSL handshakes rather than reusing connections. Check db.serverStatus().connections.created and compare it to your connection pool turnover rate.

Conclusion

In MongoDB, “Connection Pool Exhaustion” is often a misnomer for “Transaction Pinning” or “Overscaling.” Because the drivers are complex state machines interacting with Replica Sets, simply bumping maxPoolSize masks the problem until it crashes mongod via memory pressure or ticket exhaustion.

The fix is almost always:

1. Lower the pool size to match hardware (threads <= cores).
2. Shorten transaction scopes to microseconds.
3. Treat the MongoClient as a sacred singleton.

motivation

I was recently discussing with my CTO about databases. There was one point where we were thinking about the CAP theorem. Then he randomly mentioned that MySQL is not CA. I was surprised because I always thought that MySQL is a CA database at its core.

Now I had to search and understand why MySQL is not CA.

CAP theorem

We have always been taught in Engineering that CAP is one of the most important theorems in distributed systems and databases. We just accepted it. Time to question and learn ┏ʕ •ᴥ•ʔ┛

Here is what it actually means.

Imagine a bank server, when you check your account balance it should not randomly change it based on the server you are hitting and it should be consistent across all nodes. But in a distributed system, network failures (partitions) can occur. The CAP theorem states that you can only guarantee 2 out of 3 properties:

• Consistency (C): All nodes see the same data at the same time
• Availability (A): Every request receives a response, even if it’s not the most recent data
• Partition Tolerance (P): The system continues to operate despite network partitions

Here are practical examples of each combination:

CA Systems (Consistent + Available, but not Partition Tolerant)

Example: Traditional Relational Databases (like PostgresSQL in single-node setups)

Imagine a single PostgresSQL database server in a bank. When you check your balance:

• Consistency: Every time you query your balance, you get the exact same amount ($100.00)
• Availability: The system always responds to your requests
• Partition Tolerance: If the network connection to the database fails, you can’t access your account

This works perfectly in non-distributed environments, but fails when you need to scale across multiple data centers.

CP Systems (Consistent + Partition Tolerant, but sacrifices Availability)

Example: Apache ZooKeeper or etcd

Imagine a distributed configuration management system like ZooKeeper:

• Consistency: All nodes agree on configuration values (like which server is the leader)
• Partition Tolerance: If some nodes lose network connectivity, the remaining nodes continue operating
• Availability: During a network partition, some requests might be blocked to maintain consistency

In a ZooKeeper cluster, if a majority of nodes become unreachable, the system stops accepting writes to prevent inconsistent states.

AP Systems (Available + Partition Tolerant, but sacrifices Consistency)

Example: Amazon DynamoDB or Cassandra

Imagine a social media platform’s like counter system:

• Availability: The system always responds to requests, even during network failures
• Partition Tolerance: The system continues operating across multiple data centers despite network issues
• Consistency: During partitions, you might see different like counts on different servers

You might see a post with 100 likes on one page refresh, then 102 likes on the next refresh, as the systems reconcile the differences asynchronously.

Why MySQL is not CA

While MySQL can achieve CA in single-node deployments, it cannot be truly CA in distributed scenarios. When you add MySQL replicas or clustering solutions like MySQL Group Replication:

• During network partitions, MySQL must choose between consistency (rejecting writes) or availability (allowing potentially conflicting writes)
• MySQL’s synchronous replication can become unavailable during partitions if strict consistency is enforced
• Traditional asynchronous replication trades consistency for availability (so it becomes AP, not CA). Even with semi-sync replication, MySQL typically prioritizes availability over strict consistency—clients may see stale reads.

It doesn’t enforce strong ACID guarantees across replicas the way PostgreSQL doe

Why PostgreSQL is considered CA

Postgres in standalone mode: Definitely CA (strong ACID, always responds if node is up).

In replication setups:

PostgreSQL replication (especially with synchronous replication) prioritizes consistency first. A commit can be acknowledged only after replicas confirm the write (if you configure synchronous replication).

This means if replicas aren’t reachable, Postgres will prefer not to serve stale data (sacrificing availability to preserve consistency).

So Postgres is effectively CA (or CP in distributed setups).

This is why distributed databases like CockroachDB or TiDB are often preferred for truly distributed, partition-tolerant systems.

ʕ ● ᴥ ●ʔ