RSpec Connection Pool Exhaustion – Diagnose cleanup strategy

Direct answer

config.use_transactional_fixtures = true does not guarantee that a connection returns to the pool immediately after each example. It wraps the example in a transaction and rolls it back, but the connection is released only when Rails finishes with the example. If a test spawns threads, uses with_connection, or enqueues a background job that holds a connection, that slot stays checked out until the thread or job releases it. DatabaseCleaner.clean_with(:truncation) in config.after(:suite) opens its own connection to truncate tables, so it briefly consumes one pool slot while other example connections may still be open. Rails 6+ reaping closes idle connections after a timeout, but in long CI runs reaping can be delayed, which explains intermittent exhaustion rather than a consistent failure.

Likely explanation versus confirmed facts

Likely explanation

Pool exhaustion during long suites is most likely caused by connections held open by background-job-like tests or suite cleanup running while earlier connections are still checked out, not by transactional fixtures alone.

Confirmed behavior

• Transactional fixtures roll back data per example; connection return depends on Rails releasing the connection after the example ends.
• Truncation cleanup acquires its own connection and may hold table locks, increasing pool pressure during after(:suite).
• Connection reaping is timeout-based and can lag in long-running CI processes.

Steps for this case

1. Keep config.use_transactional_fixtures = true for regular examples.
2. Reserve DatabaseCleaner.clean_with(:truncation) for config.after(:suite) only, and avoid running it alongside other suite-wide tasks that open connections.
3. Add temporary pool logging after each example and around suite cleanup to confirm whether slots are released.
4. If exhaustion persists, increase the pool size in config/database.yml temporarily and re-run; if the error disappears, pool size—not fixture strategy—is the limiting factor.

Verification snippet

RSpec.configure do |config|
  config.after(:each) do
    pool = ActiveRecord::Base.connection_pool
    Rails.logger.debug "rspec after each: size=#{pool.size} checked_out=#{pool.checked_out_count}"
  end

  config.after(:suite) do
    pool = ActiveRecord::Base.connection_pool
    Rails.logger.debug "before truncation: checked_out=#{pool.checked_out_count}"
    DatabaseCleaner.clean_with(:truncation)
    Rails.logger.debug "after truncation: checked_out=#{pool.checked_out_count}"
  end
end

Missing diagnostic detail

Do any examples spawn threads, call with_connection, or enqueue jobs that retain ActiveRecord connections after the example finishes? This determines whether transactional fixtures alone are sufficient or whether leaked connections must also be reaped.