@fabricorg/experiments-db-pool

Singleton pg.Pool configured for serverless runtimes (Vercel, AWS Lambda, etc.).

Usage

import { getPool } from '@fabricorg/experiments-db-pool';

const pool = getPool();
const result = await pool.query('SELECT 1');

Singleton guarantee

getPool() returns the same Pool instance on every call within a single process:

getPool() === getPool(); // true

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DATABASE_URL | yes | — | Postgres connection string | | PG_POOL_MAX | no | 5 | Max connections in the pool |

Pool sizing rationale

Serverless platforms (Vercel, AWS Lambda, Cloudflare Pages Functions) spin up many concurrent execution environments. Each environment that creates its own Pool can hold idle connections indefinitely, exhausting the Postgres max_connections limit.

A single shared singleton eliminates duplicate pools within one process.

Default: max: 5

• Why 5? Most serverless functions are I/O-bound and rarely need more than a handful of concurrent queries.
• Why not 1? A single connection serializes all queries; 2–5 allows modest parallelism for routes that fan out (e.g. health checks + data fetches).

idleTimeoutMillis: 30000

Recycles connections after 30s of inactivity. This is half of Vercel's default serverless timeout (60s), ensuring we don't leak idle sockets across invocations.

connectionTimeoutMillis: 5000

Fail-fast when the database is unreachable. In a cold-start scenario, waiting the default 0 (infinite) can hang the function until the platform kills it.

Adjusting for your workload

If you run heavy analytics queries or batch jobs inside the same process, raise PG_POOL_MAX via environment variable rather than forking the package:

PG_POOL_MAX=20 node my-script.js