Node.js In-Depth
Module A-14·21 min read

PM2 graceful reload, pg-pool sizing mathematics, Redis Cluster client configuration, and Kubernetes liveness vs readiness probe implementation.

Written by Jatin Jain Saraf · Architect of SupraScan

Module 13 — Advanced Connection Pooling & Process Management

What this module covers: Your Node.js service processes 50,000 events/second. Every event requires a database write. That means 50,000 PostgreSQL queries/second. A naive implementation opens a new connection for every query — connection establishment costs 5–10ms and PostgreSQL cannot handle 50,000 simultaneous connections. Connection pooling is the mechanism that multiplexes thousands of queries over dozens of connections. This module covers pg-pool sizing mathematics, Redis connection management, PM2 cluster lifecycle, graceful shutdown sequences, and the Kubernetes liveness vs readiness probe distinction that prevents traffic routing before your service is ready.

Why Connection Pooling Is Not Optional

Every database connection is expensive:

  • PostgreSQL: spawns a new OS process per connection (~5MB RAM, ~10ms setup cost)
  • Redis: opens a new TCP socket per connection (~0.5ms setup, persistent)
  • MongoDB: opens a new socket, negotiates auth (~2ms)

Without pooling at 50,000 queries/second:

  • 50,000 new PostgreSQL connections/second × 10ms = 500 seconds of connection overhead per second of operation — impossible
  • At any instant, thousands of concurrent queries would require thousands of simultaneous PostgreSQL processes: 5,000 connections × 5MB = 25GB RAM just for PostgreSQL process overhead

Connection pooling solves this by reusing a small set of long-lived connections for many short-lived queries.

pg-pool: PostgreSQL Connection Pool

pg-pool (used internally by the pg package) maintains a pool of PostgreSQL connections.

The Mathematics of Pool Sizing

A connection pool is the taxi rank outside a stadium after the final whistle — too few cabs and the queue snakes around the block even though every individual ride is quick.

pool_size = (max_queries_per_second × avg_query_duration_seconds)
 
At 5,000 queries/second with 10ms average query duration:
pool_size = 5,000 × 0.010 = 50 connections

This is Little's Law applied to database connections. If you need more throughput or have longer queries, you need more connections — up to the database's limit.

import pg from 'pg';
 
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
 
  // Pool size: sized to your throughput target
  // = (target_queries_per_sec × avg_query_duration_sec)
  max: 50,
 
  // Connection idle timeout: close idle connections after 30s
  // Prevents accumulating connections that just hold resources
  idleTimeoutMillis: 30_000,
 
  // Connection acquisition timeout: fail fast if pool is exhausted
  // Without this, queries wait forever when pool is full
  connectionTimeoutMillis: 5_000,
 
  // Minimum connections to keep warm
  // Prevents cold-start latency for idle services
  min: 5,
 
  // Disconnect and reconnect after N transactions
  // Prevents long-lived connections accumulating server-side state
  maxUses: 7_500,
 
  // Controls whether the Node.js process is allowed to exit while this pool
  // still has idle or active clients. `false` keeps the event loop alive on
  // their behalf — it performs no health check of any kind, it just affects
  // process exit behavior.
  allowExitOnIdle: false,
});

Monitoring Pool State

// Monitor pool utilization in production
const poolUtilizationGauge = new Gauge({
  name: 'db_pool_utilization_ratio',
  help: 'DB pool utilization (active / max)',
});
 
const poolWaitingGauge = new Gauge({
  name: 'db_pool_waiting_count',
  help: 'Queries waiting for a connection',
});
 
setInterval(() => {
  // pg-pool exposes pool state via these properties
  const total = pool.totalCount;      // total connections (idle + active)
  const idle = pool.idleCount;        // available connections
  const waiting = pool.waitingCount;  // queries queued for a connection
 
  poolUtilizationGauge.set((total - idle) / pool.options.max);
  poolWaitingGauge.set(waiting);
 
  if (waiting > 0) {
    logger.warn({ waiting, total, idle }, 'DB pool exhausted — queries queuing');
  }
}, 5_000);

Alert thresholds:

  • db_pool_utilization_ratio > 0.8: pool approaching capacity
  • db_pool_waiting_count > 0: pool exhausted — immediate action needed
  • db_pool_waiting_count > 50: serious saturation — likely causing timeouts

Pool Exhaustion: The Silent Performance Killer

When all pool connections are busy, pool.connect() waits. At high throughput, this creates a latency cascade: query takes 15ms → pool slot held for 15ms → at 50 queries/pool × 15ms = 750ms of total query time per second → pool fully booked at 3,333 queries/second.

If your target is 5,000 queries/second:

required_pool_size = ceil(5,000 × 0.015) = 75 connections

Insufficient pool size manifests as:

  • P99 latency spikes (queries waiting for a connection)
  • connectionTimeoutMillis errors (pool exhausted for too long)
  • Not as high CPU or network errors — the service appears healthy from the outside while queries queue silently

Production story: During a festival traffic spike, a UPI payment service scaled its Kubernetes deployment from 4 replicas to 8 to absorb load, each pod running the max: 50 pool from the example above. Nobody re-ran the pool-sizing math against the replica count: 8 × 50 = 400 potential simultaneous connections to a single PostgreSQL instance configured with the default max_connections of 100. Within seconds of the new pods coming up, Postgres started rejecting new connections cluster-wide with FATAL: sorry, too many clients already — including from pods that had been running fine, because the limit is on the database, not per-service. The fix was PgBouncer in front of Postgres (below), decoupling "connections the app thinks it has" from "connections Postgres actually has to hold open."

The Missing Piece: PgBouncer (or an Equivalent External Pooler)

max: 50 on a single pod's pg.Pool is a per-process limit. It says nothing about how many processes there are. Run 8 replicas of the same service, each with max: 50, and the true ceiling against Postgres is 400 simultaneous connections — against a max_connections default that ranges from 100 to 300 depending on the managed Postgres provider. Every example pool configuration in this module has assumed a single process; at any real replica count that assumption breaks.

PgBouncer sits between your application and Postgres as a lightweight external pooler, in transaction pooling mode: it maintains a small number of real Postgres connections and multiplexes many more client connections onto them, handing a real connection to a client only for the duration of a single transaction.

Without PgBouncer:
  8 replicas × max: 50 = 400 potential connections → Postgres max_connections: 100
  → FATAL: sorry, too many clients already (at replica count, not at query volume)
 
With PgBouncer (transaction pooling):
  8 replicas × max: 50 = 400 client-side connections → PgBouncer → 20-30 real Postgres connections
  → Postgres sees a small, stable connection count regardless of how many app replicas scale up
# pgbouncer.ini
[databases]
indexer_db = host=postgres-primary port=5432 dbname=indexer
 
[pgbouncer]
pool_mode = transaction   # hand back the connection after each transaction, not each session
max_client_conn = 1000    # connections PgBouncer accepts from your app replicas
default_pool_size = 25    # real Postgres connections PgBouncer maintains per database

The trade-off: transaction pooling means session-level state (SET commands, advisory locks held across statements, LISTEN/NOTIFY) does not survive between queries from the same client connection, because the underlying Postgres connection can be handed to a different client between transactions. Anything in this module relying on session state (like maxUses recycling) needs to be re-evaluated against that constraint before adopting PgBouncer.

Connection Lifecycle: maxUses and Health Checks

Long-lived database connections accumulate state: temporary tables (from past SET commands), prepared statements, and sometimes server-side session state.

Sign in to keep reading

The rest of this module is free — sign in with Google to unlock it and track your progress.

Sign in & Register
PreviousModule A-13: Production Observability, Performance Profiling & Flame GraphsNext Module A-15: Edge Runtime Ingestion & V8 Isolates

Discussion

0

Join the discussion

Loading comments...
PortfolioBlog

© 2026 Jatin Jain Saraf (JJS). All rights reserved.