Neon compute suspended / cold-start connection timeout in CI

By Daniel Zoghalchali·Latchkey

Neon suspends idle computes to save cost. The first connection after suspension has to wake the compute, which takes a short but real amount of time. A CI client with an aggressive connect timeout gives up before the compute resumes.

What this error means

The first DB step in a job fails with "timeout expired" or "Connection terminated due to connection timeout" against Neon, then a retry a few seconds later succeeds.

Error: Connection terminated due to connection timeout
    at Connection.<anonymous> (.../pg/lib/client.js)
(the Neon compute was suspended and needed to resume)

Common causes

The compute was scaled to zero and must resume

After idle time Neon suspends the compute. The first connection triggers a resume that adds latency the client did not budget for.

The client connect timeout is too short

A one or two second connect timeout in the driver aborts before the cold start completes, so the very first query in CI fails.

How to fix it

Raise the connect timeout and retry once

1. Increase the driver connectionTimeoutMillis to comfortably exceed the cold start.
2. Wrap the first connection in a short retry so a resume never fails the job.
3. Optionally warm the compute with a trivial query before the test step.

new Pool({
  connectionString: process.env.DATABASE_URL,
  connectionTimeoutMillis: 15000,
})

Warm the branch before running tests

Issue a cheap query as its own step so the compute is already awake when the suite starts.

- run: psql "$DATABASE_URL" -c "select 1" || sleep 3 && psql "$DATABASE_URL" -c "select 1"

How to prevent it

• Set a generous driver connect timeout in CI to cover cold starts.
• Warm the compute with a trivial query before the test suite.
• Retry the first connection instead of failing the whole job.

Frequently asked questions

Related guides

References

• GitHub Actions documentation