fix: recover from half-open postgres connections with bounded liveness ping

[TimoGlastra]

Problem

The postgres pool is built with .test_before_acquire(false), and sqlx sets no TCP keepalive. A pooled connection that died while idle is therefore handed out untested, and the first operation on it fails — or worse, hangs.

Two distinct failure modes:

• Clean drop (server closed the connection, FIN/RST received): the next operation errors immediately. Annoying but fast.
• Half-open drop (connection silently discarded by intermediate infrastructure — NAT gateways, Cloud Run, load balancers all document doing this to idle TCP flows): the next operation just hangs. The kernel keeps retransmitting for ~15 minutes and there is no timeout at any layer above it.

Why not just test_before_acquire(true)

That fixes the clean-drop case transparently (the ping fails instantly, sqlx discards the connection and redials within the same acquire). But for a half-open connection the test ping itself hangs, and since it shares the overall acquire_timeout deadline, the whole acquire still fails after connect_timeout — even though the database is perfectly reachable.

Fix

A before_acquire hook that pings idle connections under its own short deadline. A hung ping counts as a failed test, so the pool discards the connection and moves on to another one or a fresh dial, all within the regular acquire timeout. Connections used within the last second skip the ping, keeping hot-path overhead at zero — the same heuristic pgxpool uses (see jackc/pgx#1838).

Validation

Tested against a local postgres behind a TCP proxy that can (a) cleanly kill connections, (b) silently blackhole existing connections while new ones work, (c) blackhole everything. URI: connect_timeout=4&idle_timeout=60&max_connections=30; each check = store.session().open() + fetch + close.

Scenario	stock v0.5.0	test_before_acquire(true)	bounded ping (this PR)
idle conns killed cleanly	error per dead conn	OK ~20ms	OK ~20ms
idle conns half-open, DB fine	hung 20s+ (unbounded)	error at 4s (acquire timeout)	OK ~1s, no error
DB fully unreachable	hung (unbounded)	error at 4s	error at 4s (correct)

With this change, callers never see an error for a connection that died while idle as long as the database is actually reachable: each dead connection just adds ~ping_timeout to the first acquire that touches it.

Additionally, the full postgres backend test suite passes with min_idle_for_ping=0 (ping forced on every acquire), confirming the hook does not discard healthy connections.

Configuration

Two new postgres URI query parameters, following the existing option conventions (whole seconds):

• ping_timeout (default 1): deadline for the liveness ping on an idle connection. 0 disables the check entirely, restoring the previous behavior.
• min_idle_for_ping (default 1): minimum time a connection must have been idle before it is pinged on acquire. 0 pings on every acquire.

The sqlite backend also sets test_before_acquire(false) but is left untouched, since a liveness ping is meaningless for a local file database.

🤖 Generated with Claude Code