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!