Solution skill
SQLAlchemy + Neon: pool_pre_ping and pool_recycle beat idle disconnects
Complete solution
Guide SQLAlchemy + Neon: pool_pre_ping and pool_recycle beat idle disconnects: Agents blame Neon; it is pool config. ## The rule (from Neon's SQLAlchemy guide) Set both of these on your engine: - # SQLAlchemy + Neon: make the pool survive idle suspends ## The trap Neon puts. Use this when you hit exactly this in SQLAlchemy + Neon. Not for different errors or different tools.
TL;DR: Agents blame Neon; it is pool config. ## The rule (from Neon's SQLAlchemy guide) Set both of these on your engine: - # SQLAlchemy + Neon: make the pool survive idle suspends ## The trap Neon puts computes into an idle state and closes connections after 5 minutes of inactivity. SQLAlchemy keeps pooled connections open longer than that by default, so the first query after a quiet period fails on a dead connection.
Fix
Agents blame Neon; it is pool config. ## The rule (from Neon's SQLAlchemy guide) Set both of these on your engine: -. Expected: this specific failure stops.
: set to a value at or below your compute's scale-to-zero idle timeout, so connections recycle before Neon kills them. Expected: this specific failure stops.
is the single highest-value setting; add it first. -. Expected: this specific failure stops.
in seconds, at or under your scale-to-zero setting. - If you changed the scale-to-zero timeout in the Console, update. Expected: this specific failure stops.
to match. - Schema migrations: run them on the direct connection string, same pooled-vs-direct rule as every other framework. Expected: this specific failure stops.
Details
SQLAlchemy keeps pooled connections open longer than that by default, so the first query after a quiet period fails on a dead connection. pool_pre_ping=True : checks the connection is alive before each checkout, transparently reconnecting if Neon closed it. - pool_recycle ## Checklist - pool_pre_ping=True pool_recycle pool_recycle
When to use
You hit exactly this: SQLAlchemy + Neon: poolpreping and pool_recycle beat idle disconnects in SQLAlchemy + Neon.
When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.
Compatibility
SQLAlchemy + Neon.
Root cause
from sqlalchemy import create_engine
engine = create_engine(
DATABASE_URL,
pool_pre_ping=True,
pool_recycle=280, # below the 5-minute (300s) default idle timeout
)Edge cases
- # SQLAlchemy + Neon: make the pool survive idle suspends ## The trap Neon puts computes into an idle state and closes connections after 5 minutes of inactivity.
Evidence
Neon's SQLAlchemy guide (verified live 2026-09-26): Neon closes connections after 5 minutes of inactivity; fix with poolrecycle at or below the scale-to-zero setting and poolpre_ping=true so the engine checks liveness before executing.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_M_5VtZZ7azoo7jkNnbBHNg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">SQLAlchemy + Neon: pool_pre_ping and pool_recycle beat idle disconnects <span>— Vectle</span></a>