Skip to content

How Many Connections Does Your Rails App Need? Sizing and Observing the Active Record Pool in 2026

TL;DR

Pool size is a cap on concurrent database work, not a guess. Add up web processes, queues and deploy overlap, then compare with Postgres max_connections. In Rails 8.1 the old pool: key is called max_connections. Measure saturation with checkout_wait.active_record, and only then decide whether you need PgBouncer.

Threads, fibers and workers change the pool math. The new checkout_wait.active_record event lets you measure saturation without monkey-patching ConnectionPool. This post works that math, configures database.yml for a real Rails 8.1 app, and decides when PgBouncer belongs.

Published 13 min read

Also available in Português (Brasil)

Share

Every thread, fiber or worker in a Rails app wants a Postgres connection. The number you put in max_connections — the former pool: — is not a performance knob you tune by feel. It is the cap on how much concurrent work that process can do against the database. Blow past the cap and the request waits. Blow past checkout_timeout and the wait becomes an ActiveRecord::ConnectionTimeoutError in the middle of the day.

Until November 2026, measuring that required a monkey-patch on ConnectionPool. In This Week in Rails on November 6, Rails started emitting a checkout_wait.active_record event: it fires only when a checkout has to wait because the pool is full, reports that wait as the event's duration, and, if the wait times out, carries the error in the payload. This post works through the calculation almost nobody does — the same one that changes when you swap Puma for Falcon or Pitchfork, and when Solid Queue shares the same Postgres — configures database.yml for a real Rails 8 app, and turns that metric on before you decide whether PgBouncer belongs in the picture.

1. The calculation nobody does

A Rails process has one pool per configured database. Clustered Puma, Pitchfork and the Solid Queue process are different processes, each with its own pool. Two Puma workers with max_connections: 5 do not share five connections: they are ten. Add Kamal replicas, and add them again at deploy time, when the old release and the new one overlap.

The formula looks like this:

Postgres connections ≈
    (web processes × primary max_connections)
  + (web processes × cache and cable max_connections,
     if they share the same server)
  + (queue processes × queue max_connections
     + primary max_connections, because the job
     also queries the application)
  × (and during a deploy, count the old release and the new one)

A concrete example, on a single VPS, nothing exotic:

  • Puma with 2 workers and 5 threads. Each worker opens the primary pool and, on the Solid Trio, the cache and cable pools. That is 2 × (5 + 5 + 5) = 30 connections.
  • One Solid Queue process with 5 threads. The workers need the queue database and, to run the job, the primary as well. That is at least 10 more.
  • Steady-state total: 40 connections. During a deploy with overlap, 80. Postgres defaults to max_connections = 100, and some of those are reserved for the superuser. The headroom that looked comfortable fits in one hand.

The arithmetic changes with the app server, which is why this post follows on from the Puma, Falcon and Pitchfork comparison.

Puma. Each thread can hold a connection. max_connections on primary should be at least RAILS_MAX_THREADS. The generated database.yml already ties those together; the classic mistake is raising Puma's threads and forgetting the pool cap.

Falcon. Requests run as fibers on the same thread. With config.active_support.isolation_level = :fiber — and that line has to be there, otherwise every fiber shares the same lease and the same query cache — each fiber can have its own connection. Since Rails 7.2, an ordinary find returns the connection at the end of the query, so the pool does not need to equal your peak concurrent fibers. What exhausts the pool is a permanent checkout: ActiveRecord::Base.connection holds the connection until the request finishes. On a fibered app, that is:

# config/application.rb, in an app running on Falcon
config.active_support.isolation_level = :fiber
config.active_record.permanent_connection_checkout = :disallowed

:disallowed turns a permanent checkout into an error already in development, which is exactly what you want to find before peak hours.

Pitchfork. Each worker is a process that handles one request at a time, in the Unicorn style. max_connections: 1 or 2 per worker is enough. The danger is in the product: 32 workers across 3 replicas are already dozens of connections, even with a tiny pool.

Action Cable. If Cable runs inside the same Puma, the cable pool is in each worker's total. If it runs as a separate process, it is another line in the sum.

The real ceiling is not Rails, it is Postgres: SHOW max_connections. On a small RDS instance that number is often low, derived from memory. Anything past it is refused with FATAL: too many connections, which is a different error from a pool timeout and usually a worse one: it hits even rails console and the process you would send in to investigate.

2. Configuring database.yml for real

In Rails 8.1, pool size is called max_connections. pool: still works, but it is deprecated, and the framework's warning points at removal in 8.2. Setting both, at different values, prevents boot with a RuntimeError. Adding min_connections while leaving the old pool: in place is also rejected: when you adopt the new options, rename the key in the same commit.

# config/database.yml
default: &default
  adapter: postgresql
  encoding: unicode
  max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  checkout_timeout: 5
  idle_timeout: 300
  # AWS NAT Gateways close idle connections at 350s.
  # The keepalive default is 600, so on AWS this has to come down.
  keepalive: 300
  # Recycle old connections on the next checkin, with jitter
  # so they are not all retired at once.
  max_age: <%= 1.hour.to_i %>

production:
  primary: &primary_production
    <<: *default
    host: <%= ENV.fetch("DB_HOST") %>
    database: rubyinsights_production
    username: rubyinsights
    password: <%= ENV["DATABASE_PASSWORD"] %>
  cache:
    <<: *primary_production
    database: rubyinsights_production_cache
    migrations_paths: db/cache_migrate
    max_connections: <%= ENV.fetch("CACHE_MAX_CONNECTIONS") { 5 } %>
  queue:
    <<: *primary_production
    database: rubyinsights_production_queue
    migrations_paths: db/queue_migrate
    max_connections: <%= ENV.fetch("JOB_CONCURRENCY") { 5 } %>
  cable:
    <<: *primary_production
    database: rubyinsights_production_cable
    migrations_paths: db/cable_migrate
    max_connections: <%= ENV.fetch("CABLE_MAX_CONNECTIONS") { 5 } %>

What each key actually does:

  • max_connections is the cap for that pool, in that process. Default 5. It can be nil or -1 for unlimited, which is almost never what you want in production.
  • min_connections is the floor the pool tries to keep open (default 0). It avoids the cost of opening a connection on the first request after an idle stretch.
  • checkout_timeout is how long a thread or fiber waits for a free connection before raising ActiveRecord::ConnectionTimeoutError. Default 5 seconds. Raising this number does not create connections: it only leaves the request hanging for longer.
  • idle_timeout is how long an idle connection lives in the pool before the reaper disconnects it. Default 300 seconds. 0 keeps it forever.
  • keepalive sends a periodic signal on idle connections so the server — and any NAT on the path — does not close them. Default 600 seconds, which is too high behind an AWS NAT Gateway, whose idle timeout is 350.
  • max_age retires the connection on the next checkin, once it is that old. Default infinity. Useful for recycling connections when a load balancer or a DNS change sits in front. pool_jitter (default 0.2) spreads those retirements so they do not coincide.
  • reaping_frequency is how often the reaper runs, calling reap and flush. If you lower idle_timeout, the reaper needs to be at least as frequent as that timeout.

The four Solid Trio databases — primary, cache, queue, cable — are four pools. Even when they are four databases on the same Postgres, each one counts against the server's max_connections. Treating "pool 5" as "five connections in total" is the mistake that closes the margin in the section 1 example.

3. Measuring saturation

The checkout_wait.active_record event does not fire on every checkout. It fires only when the pool is full and someone has to wait. The event's duration is that wait, in milliseconds. The payload carries the pool itself in :connection_pool and the wait cap in :checkout_timeout. If the wait exceeds the cap, the payload includes :exception with the ActiveRecord::ConnectionTimeoutError.

That is enough for an initializer that feeds your APM and an alert:

# config/initializers/connection_pool_metrics.rb
ActiveSupport::Notifications.subscribe("checkout_wait.active_record") do |event|
  pool = event.payload[:connection_pool]
  pool_name = pool.db_config.name.to_s
  tags = ["pool:#{pool_name}"]

  StatsD.distribution("active_record.checkout_wait", event.duration, tags: tags)

  if event.payload[:exception]
    StatsD.increment("active_record.checkout_timeout", tags: tags)
    Rails.logger.warn(
      "[connection_pool] checkout timed out after #{event.duration.round(1)}ms " \
      "(checkout_timeout=#{event.payload[:checkout_timeout]}s, pool=#{pool_name})"
    )
  end
end

StatsD.distribution is the Datadog style; the OpenTelemetry equivalent is a histogram on the meter, with a db.pool.name attribute. What matters is splitting the pools: a wait on queue is a job-concurrency problem, a wait on primary is a web-request problem, and mixing them on the same graph hides both.

Two alerts are enough to start:

  1. Any increment of active_record.checkout_timeout in a 5-minute window. That is already a failing request, not a degradation.
  2. p95 of active_record.checkout_wait above 100 ms for 10 minutes. The pool is still handing out connections, but it is saturated: the next spike becomes a timeout.

Short, occasional waits are normal. A steady queue of waits is the pool saying it is too small, or that something is holding a connection too long — the diagnosis in section 6 tells those apart.

4. PgBouncer or not?

The Active Record pool lives inside a process. It does not help when the problem is many processes adding up against a low ceiling on RDS. That is where PgBouncer comes in: Rails processes open many client connections to the bouncer, and the bouncer keeps a smaller set of server connections to Postgres.

There are three modes, and only two belong in the conversation:

  • Session. A server connection stays with the client for as long as the Rails session exists. Every Postgres feature works, including session locks and PREPARE. The multiplexing gain is small, because the connection only returns to the pool when the client disconnects.
  • Transaction. The server connection is returned at the end of each transaction. This is the mode that actually reduces connections on Postgres. It is also the mode that breaks session state.
  • Statement. Like transaction, but it forbids multi-statement transactions. Do not use it with Rails.

What breaks in transaction mode is specific, and a short list is worth it:

  • Session advisory locks (pg_advisory_lock) do not survive, because the next transaction may land on a different server connection. Row locks, including the FOR UPDATE SKIP LOCKED Solid Queue uses to claim jobs, work as usual.
  • SQL PREPARE and DEALLOCATE do not work. Protocol-level prepared statements, which is what the Rails pg adapter uses, work on PgBouncer 1.21 or later with max_prepared_statements set to something other than zero — and in recent versions that is already on, defaulting to 200.
  • Session LISTEN/NOTIFY, WITH HOLD cursors and temporary tables that outlive the transaction also do not. If your application depends on any of those, session mode is the choice, or PgBouncer is the wrong tool.

In practice, a Rails 8 app with Solid Queue, Solid Cache and Solid Cable on the same Postgres is fine with transaction mode, protocol-level prepared statements, and the bouncer's default_pool_size sized to the ceiling RDS will actually tolerate. Rails max_connections can even be more generous: it now caps connections against the bouncer, not against Postgres.

Rails points at PgBouncer in database.yml (port: 6432, typically). The bouncer is what points at Postgres, with a default_pool_size per database. Two operational rules: do not put the bouncer in front of a connection that needs a session, and do not share the same default_pool_size between a busy queue database and primary if they have different load patterns — PgBouncer has per-database pools too, use them.

5. Decision table by scenario

The numbers below are starting points, not law. What counts is checkout_wait after a day of real traffic.

Scenariomax_connections per processPgBouncerWhat to monitor
Monolithic Puma, one process, 5 threads5, matching RAILS_MAX_THREADSNo, unless the Postgres ceiling is already tightcheckout_wait on primary; pg_stat_activity
Falcon with fibersStart at 5–15, not at peak fibers; isolation_level = :fiber and permanent checkout :disallowedOnly if many workers push the total upcheckout_wait duration and connections held until the request ends
Pitchfork, many workers1 or 2 per workerYes, when workers × replicas approach the ceilingTotal Postgres connections at peak and during deploys
Kamal with several replicasThe same per process, multiplied by replicas, with headroom for deploy overlapYes, when that sum approaches the RDS ceilingTotal connections against the server's max_connections
Solid Queue on the same Postgresqueue pool equal to worker concurrency, plus the primary that jobs also useTransaction mode is fine: Solid Queue uses FOR UPDATE SKIP LOCKEDcheckout_wait on queue and primary, separately
RDS with a low ceilingSmall, explicit pools on each Solid Trio databaseYes, transaction modeThe RDS connection metric and any checkout_timeout

If the table is pulling you toward PgBouncer and you have not yet measured a checkout_wait, measure first. A bouncer placed in the dark trades a problem you cannot see for two.

6. Production checklist

The classic symptom shows up in the application logs:

ActiveRecord::ConnectionTimeoutError:
  could not obtain a connection from the pool within 5.000 seconds

Five seconds is the default checkout_timeout. Postgres may be idle at that exact moment: the timeout belongs to that process's pool, not to the server. Before you raise max_connections in the dark, walk this list.

1. Confirm who is waiting. The checkout_timeout alert and the p95 of checkout_wait, broken down by pool, tell you whether the problem is web, queue, cache or cable.

2. Look at what Postgres sees.

SELECT datname, usename, state, wait_event_type, wait_event,
       LEFT(query, 80) AS query, state_change, backend_start
  FROM pg_stat_activity
 WHERE backend_type = 'client backend'
 ORDER BY state, state_change;

What you are looking for: how many rows there are against SHOW max_connections, and how many are idle in transaction. An open transaction holds the connection in Rails and the connection in Postgres. The most common cause is slow work inside the transaction: an HTTP call to a third party, an upload, a Solid Queue job that opens the transaction at the start and only commits after talking to an external service.

3. Hunt for held connections in the app. ActiveRecord::Base.connection (the permanent checkout) in a job or a fiber; a Thread.new that takes a connection and never returns it. The permanent_connection_checkout = :disallowed from section 1 helps here too, even on Puma.

4. Check the deploy arithmetic. If the timeouts only appear during kamal deploy, you do not have a small pool: you have overlap with no headroom on the Postgres ceiling. PgBouncer, or a server max_connections that can hold two releases, fixes it; raising each process's pool makes it worse.

5. Do not raise checkout_timeout as a fix. That only delays the error. If the pool is saturated, the request is already slow. The fix is to return connections sooner, or to raise the pool after you redo the section 1 sum against the server ceiling.

6. Keep Postgres statement_timeout separate. It cancels a slow query. checkout_timeout cancels the wait for a connection. They are different levers, and one does not replace the other.

When the numbers add up, an ordinary GET on a well-sized app does not even emit checkout_wait. The event is there for the day that changes — one more worker, a new replica, a job that started holding a transaction — and you see the saturation before the first 500.

Start with the sum, move database.yml to max_connections, turn the subscriber on and live with the two alerts for a week. Only then change the pool size or put PgBouncer in front. A pool you do not measure is a bug you have not found yet.

Sources

  1. This Week in Rails: November 6, 2026 rubyonrails.org
  2. Rails Guides: Active Support Instrumentation guides.rubyonrails.org
  3. Rails Guides: Configuring Rails Applications — database pooling guides.rubyonrails.org
  4. ActiveRecord::ConnectionAdapters::ConnectionPool (Rails 8.1) api.rubyonrails.org
  5. Rails Guides: Multiple Databases with Active Record guides.rubyonrails.org
  6. rails/solid_queue github.com
  7. PgBouncer: Features www.pgbouncer.org
  8. PostgreSQL: Connection and Authentication www.postgresql.org
  9. AWS: NAT gateway troubleshooting (idle timeout) docs.aws.amazon.com

FAQ

pool: or max_connections: in Rails 8.1?

Use max_connections. pool: still works, but it is deprecated in 8.1 and the framework's warning points at removal in 8.2. Do not set both at different values, and do not mix the old pool: with min_connections: either case prevents boot.

Do I need a pool as large as the number of fibers on Falcon?

No. Since Rails 7.2 an ordinary find returns the connection at the end of the query. Set isolation_level = :fiber and permanent_connection_checkout = :disallowed, start with a pool of 5 to 15 and let checkout_wait tell you whether you are short. What exhausts the pool is a permanent checkout, not the fiber count.

Why do I get ConnectionTimeoutError when Postgres still has free connections?

The timeout belongs to that process's pool, not to the server. Common causes: another Solid Trio pool eating into the budget, deploy overlap, a transaction holding the connection (idle in transaction), or a permanent checkout. Look at checkout_wait broken down by pool and at pg_stat_activity before raising the cap.

Does PgBouncer in transaction mode break Solid Queue?

No. Solid Queue claims jobs with FOR UPDATE SKIP LOCKED, which is a row lock and works in transaction mode. What breaks in that mode is session advisory locks, SQL PREPARE, LISTEN, and temporary tables that outlive the transaction. Protocol-level prepared statements work on PgBouncer 1.21 or later.

Does the checkout_wait event fire on every checkout?

No. It is only emitted when the pool is full and the checkout has to wait. The duration is that wait, in milliseconds. If checkout_timeout is exceeded, the payload carries the ActiveRecord::ConnectionTimeoutError in :exception. Requests that get a free connection produce no event.

How should I size this with several Kamal replicas?

Multiply one process's usage by the number of replicas and leave headroom for deploy overlap, when two releases run at once. If that sum approaches the RDS ceiling, bring in PgBouncer in transaction mode; raising each process's pool at that point only tightens the server.

Comments

Sign in with GitHub to comment.

No comments yet.