Proposal: Idle connection cleanup mechanism for async pool

[medikos]

Summary

I’d like to suggest adding an optional mechanism for cleaning up idle connections in the pool.

Problem

In high-load scenarios, the pool can grow significantly (up to max_connections). But when the load drops, those connections remain open even if they're no longer needed. Over time, this can lead to resource waste — unnecessary open sockets, memory usage, etc — especially in long-running apps.

Currently, there’s no way to automatically shrink the pool when the demand goes down.

Suggested solution

I propose adding a simple mechanism that periodically checks idle connections and closes those that have been unused for longer than a configurable timeout.

How it would work:

• When a connection is released via context manager and added back to the free pool, we record the exact timestamp (last_used_time) — this is when the idle timer starts.
• Free connections are stored in a deque. Newly returned connections are added to the right, and we always check the leftmost one (i.e. the one that's been idle the longest).
• Every check_interval seconds, the pool performs the following:
  • If the total number of connections exceeds min_connections, and
  • The idle duration of the oldest free connection exceeds idle_timeout
    → Then we close that connection and remove it from the pool.

This approach is simple, efficient (O(1) with deque), and does not interfere with normal connection usage.

Config options

• min_connections — don’t shrink below this number (e.g. 10)
• idle_timeout — how long a connection can stay idle before it's closed (e.g. 60 sec)
• check_interval — how often to perform idle cleanup (e.g. 30 sec)
• enable_idle_reaping (optional) — opt-in flag for enabling the behavior

Happy to contribute

If this sounds useful, I’d be glad to put together a PR with an optional implementation that’s well-contained, tested, and backward-compatible. Let me know your thoughts!

[itssimon]

Sounds like a good idea to me!

[long2ice]

Confirmed the gap on dev: the pool grows to its high-water mark and never shrinks — after 8 concurrent holders on a minsize=2, maxsize=8 pool, pool_size stays at 8 with all 8 idle. The 0.4.0 health checks don't help here; they discard dead connections, while a live-but-unneeded one is kept forever. So the proposal stands, and a PR would be welcome.

Two suggestions for the implementation:

1. Reap under the existing Pool._lock, reusing _discard_connection and _ensure_minsize_connections, so it can't race an in-flight acquire.
2. The last_used_time you're already adding solves a second problem worth bundling: every checkout currently costs two PING round-trips (liveness check on acquire and on release). That's invisible on localhost but is 2 extra RTTs per checkout in production — a "verified within the last N ms" grace window keyed off the same timestamp would remove most of it.

[long2ice]

Implemented on dev in 209bb89 — thanks for the proposal and the design sketch, both suggestions from it went in.

Pool(minsize=2, maxsize=8, idle_timeout=30)   # reap connections idle >30s, down to minsize

Reaping runs on release while holding Pool._lock, reusing the existing _discard_connection, so it cannot race an in-flight acquire. The default stays None (no reaping), preserving current behaviour. Verified: a minsize=1, maxsize=4 pool grows to 4 under load and returns to 1 once the connections go idle past the timeout.

I also bundled the second point discussed above: the last_used timestamp the reaper needs now lets a connection verified on release skip its ping when acquired again within liveness_grace (1 s by default). That halves the liveness pings per checkout — measured 100 → 51 over 50 checkouts — which is invisible on localhost but saves an RTT per checkout in production.