Add stale connection recovery to prevent pool exhaustion

[claudear]

Summary

• Adds maxUseTime configuration to Pool that enables detection of leaked connections (connections checked out longer than the threshold)
• When the pool is exhausted and stale connections are detected, their slots are recovered allowing new connections to be created
• Tracks checkout timestamps on Connection objects via markCheckedOut()/getCheckedOutAt()
• Feature is opt-in (disabled by default with maxUseTime=0) for full backwards compatibility

Problem

The Sentry error "Pool 'console' is empty (size 75)" (CLOUD-3K4N, 3267 events) occurs when all pool connections are checked out and none are returned. This happens when connections are leaked — popped but never reclaimed due to consumer code errors, timeouts, or edge cases. Without recovery, leaked connections permanently reduce pool capacity until full exhaustion.

How it works

1. Each connection records a timestamp when checked out (markCheckedOut())
2. When pop() fails to get a connection and maxUseTime > 0, it scans active connections for any exceeding the threshold
3. Stale connections are removed from tracking and their slots freed (connectionsCreated decremented)
4. The retry loop then creates a fresh connection in the freed slot

Test plan

• testPoolRecoversStaleConnections — verifies stale connections are detected and new connections created in their place
• testPoolDoesNotRecoverNonStaleConnections — verifies non-stale connections are not evicted
• testPoolStaleRecoveryDisabledByDefault — verifies the feature is off when maxUseTime=0
• All 90 existing tests pass
• Lint (pint --preset psr12) passes
• Static analysis (phpstan) passes

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@claudear has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 18 minutes and 36 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c005a3f8-8180-4bce-abd7-e285a80c13f9

📥 Commits

Reviewing files that changed from the base of the PR and between 3634543 and 6ea686f.

📒 Files selected for processing (3)

• src/Pools/Connection.php
• src/Pools/Pool.php
• tests/Pools/Scopes/PoolTestScope.php

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/stale-connection-recovery

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}