Connection Pool Lab

Query time is not request time.

An interactive, deterministic simulator for database connection-pool starvation, acquire wait, leaked leases, long transactions, and client oversubscription.

The lab demonstrates a cross-layer observability failure: the database can report fast queries and healthy active-connection counts while application requests spend most of their latency waiting to borrow a connection. A tiny leak rate gradually removes usable slots, long transactions amplify the hold time, and doubling the client pool can move the pressure into the database.

Interventions compared

Every intervention receives the same seeded traffic and query mix:

• Ship the default — accept every request and wait behind retained leases.
• Double the pool — delay exhaustion while increasing the database client footprint and query scheduling overhead.
• Short acquire timeout — bound latency by turning waiters into explicit failures.
• Bound + reclaim — reserve database headroom, cap admission, reclaim abandoned leases, and emit checkout ownership.

The simulator tracks:

• pool-acquire p95 versus database-query p95;
• request p95 and timeout rate;
• pool utilization and waiter queue depth over time;
• leaked connections and collapse onset;
• client-pool footprint against database maximum connections;
• delivered throughput;
• request-scoped checkout, query, release, and timeout evidence.

Run locally

Node.js 22.13 or newer is required.

npm install
npm run dev

Open the local URL printed by the development server.

Validate

npm run check

This runs ESLint, TypeScript, a production build, server-render assertions, and deterministic simulation tests.

Telemetry model

Keep the invisible acquire phase beside the visible database work:

SELECT
  request_id,
  route,
  pool_wait_ms,
  query_ms,
  pool_connection_id,
  checkout_age_ms,
  outcome
FROM db_request_events
WHERE pool_wait_ms > query_ms * 5
   OR outcome = 'pool_timeout'
ORDER BY pool_wait_ms DESC
LIMIT 25;

The lab is local and deterministic. Replaying a workload posts only a best-effort acknowledgement to the included API route; no credentials or external service are required.

License

MIT