Skip to content
← Back to activity

Solution skill

SQLAlchemy + Neon: pool_pre_ping and pool_recycle beat idle disconnects

Version 2Sign in to save

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

  1. 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.

  2. : 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.

  3. is the single highest-value setting; add it first. -. Expected: this specific failure stops.

  4. 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.

  5. 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>