Rails ConnectionTimeoutError under Puma: pool.stat shows waiting threads, but raise the pool or release connections earlier?

Answer first

With busy == pool size and waiting > 0 you have pool exhaustion. Do not raise the pool until you know total connection demand vs DB max_connections and whether connections are held across non-DB work.

Decision rule:

• Raise pool size only if total demand is safely below DB max_connections and hold time is short.
• Scope checkouts with ActiveRecord::Base.with_connection when connections are held for external HTTP calls, background jobs, or other I/O and the DB budget is shared with Sidekiq.

Likely explanation vs confirmed facts

Confirmed: ActiveRecord::Base.connection_pool.stat shows busy == size and waiting > 0 during incidents. That is pool exhaustion, not DB unavailability. Puma threads exceed pool size.

Likely: Checkouts are held for the full request because a slow external HTTP call runs after a query and the Rails executor releases the connection only at end of request. This inflates hold time and makes exhaustion appear under moderate load.

Criteria to choose pool increase vs early release

1. Calculate total demand: sum of pool_size per Puma worker process plus Sidekiq concurrency pools. Compare to DB max_connections with headroom for admin connections.
2. If demand >= max_connections, raising pool is unsafe. Prefer early release.
3. If hold time of a checkout is dominated by non-DB work, scope DB work. If hold time is dominated by DB query time and concurrent DB-using threads consistently saturate the pool, sizing may be justified.

pool.stat patterns

Sample stat during incidents and correlate with request traces.

ActiveRecord::Base.connection_pool.stat
# => {:size=>5, :connections=>5, :busy=>5, :dead=>0, :idle=>0, :waiting=>3}

• Pool too small: busy == size, waiting > 0, average checkout hold time is short and close to query time. Threads are blocked waiting for a DB-using slot.
• Connections held too long: busy == size, waiting > 0, hold time is long and spans external HTTP calls, rendering, or other I/O. Pool is sufficient for concurrent DB work but connections are not released promptly.

With Sidekiq sharing the same database

Allocate the DB connection budget across web and workers. Raising web pool reduces headroom for Sidekiq and increases risk of DB-wide exhaustion.

Preferred approach when shared:

• Cap web pool to min(puma_threads, safe_web_share) and keep sidekiq pool separate.
• Scope DB work with with_connection around queries only, releasing before external calls.
• Monitor total connections from pg_stat_activity or equivalent and enforce sum < max_connections * 0.8.

Version-sensitive API note

ActiveRecord::Base.with_connection is available from Rails 7.1. Rails 7.2 deprecates .connection to .lease_connection naming. Confirm Rails version before adopting and avoid holding a connection across external calls.

Steps needed for this case

1. Record DB max_connections and current total connections from all Puma workers and Sidekiq processes.
2. Instrument checkout hold time to confirm connections are retained across external HTTP calls.
3. If budget allows and hold time is short, align pool size to concurrent DB-using threads and ensure puma threads >= pool size is intentional.
4. If budget constrained or hold time is long, wrap DB sections with with_connection and release before external I/O.

One missing diagnostic that changes the recommendation: the current DB max_connections value and the measured average checkout hold time during incidents. Without those, sizing vs scoping cannot be safely decided.