Neon "too many connections" (use the pooler endpoint) in CI

Neon's direct endpoint caps concurrent connections at a small number tied to the compute size. Parallel CI jobs each opening their own connection exhaust that cap. The -pooler endpoint multiplexes many clients over few backend connections and is the fix.

What this error means

Parallel test jobs against Neon fail with "FATAL: sorry, too many clients already" or "remaining connection slots are reserved". It appears once concurrency rises, not on a single job.

psql

FATAL:  sorry, too many clients already
FATAL:  remaining connection slots are reserved for non-replication superuser connections

Common causes

CI connects to the direct endpoint under high concurrency

The direct compute endpoint allows only a limited number of simultaneous connections. A test matrix or parallel workers open more than that at once and are refused.

Connections are not released between test cases

A test suite that opens a client per case without pooling or closing leaks connections until the compute cap is hit.

How to fix it

Use the -pooler endpoint host

Switch DATABASE_URL to the pooled host that ends in -pooler.
PgBouncer in transaction mode fronts the compute, so many CI clients share few backend connections.
Keep the direct host only for migrations that need session features.

.github/workflows/ci.yml

# pooled host multiplexes CI connections
DATABASE_URL=postgres://user:pass@ep-cool-name-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require

Cap the client pool size in the app

Bound the per-process pool so a parallel matrix cannot exceed the compute limit even on the pooled endpoint.

db.js

# example: node pg pool
new Pool({ connectionString: process.env.DATABASE_URL, max: 5 })

How to prevent it

Route CI app connections through the Neon -pooler endpoint.
Set an explicit max pool size that fits the compute connection limit.
Close connections deterministically at the end of each test worker.