Postgres "FATAL: sorry, too many clients already" in CI

Postgres refused a new connection because the number of open connections reached max_connections. Something is opening more connections than the server allows - typically parallel test workers or connections that are never closed.

What this error means

Tests or migrations fail intermittently with "FATAL: sorry, too many clients already", often once parallelism ramps up. It correlates with the number of concurrent workers, not with database readiness.

psql: error: connection to server failed:
FATAL:  sorry, too many clients already

Common causes

Parallel workers each open a pool

Test runners that fork many workers, each with its own connection pool, can multiply connections past the small default max_connections of a CI container.

Leaked connections

Connections opened per test/request but never closed accumulate until the limit is hit.

max_connections too low for the workload

The container image ships a modest default that a parallel CI run can exhaust.

How to fix it

Raise max_connections on the service

Bump the limit for the ephemeral CI database.

services:
  postgres:
    image: postgres:16
    env: { POSTGRES_PASSWORD: postgres }
    options: >-
      --health-cmd "pg_isready"
      -c max_connections=200

Cap pool size and close connections

1. Set a small per-worker pool size so workers x pool stays under the limit.
2. Ensure connections are closed/released after each test or request.
3. Consider a pooler (PgBouncer) for high parallelism.

How to prevent it

• Size connection pools relative to max_connections and worker count.
• Close connections deterministically in test teardown.
• This is a capacity/leak problem, not transient - retrying alone will not fix a genuine over-subscription.

Related guides