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.
Also available in Português (Brasil)
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
primarypool and, on the Solid Trio, thecacheandcablepools. That is 2 × (5 + 5 + 5) = 30 connections. - One Solid Queue process with 5 threads. The workers need the
queuedatabase and, to run the job, theprimaryas 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_connectionsis the cap for that pool, in that process. Default 5. It can benilor-1for unlimited, which is almost never what you want in production.min_connectionsis 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_timeoutis how long a thread or fiber waits for a free connection before raisingActiveRecord::ConnectionTimeoutError. Default 5 seconds. Raising this number does not create connections: it only leaves the request hanging for longer.idle_timeoutis how long an idle connection lives in the pool before the reaper disconnects it. Default 300 seconds.0keeps it forever.keepalivesends 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_ageretires 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_frequencyis how often the reaper runs, callingreapandflush. If you loweridle_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:
- Any increment of
active_record.checkout_timeoutin a 5-minute window. That is already a failing request, not a degradation. - p95 of
active_record.checkout_waitabove 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 theFOR UPDATE SKIP LOCKEDSolid Queue uses to claim jobs, work as usual. - SQL
PREPAREandDEALLOCATEdo not work. Protocol-level prepared statements, which is what the Railspgadapter uses, work on PgBouncer 1.21 or later withmax_prepared_statementsset to something other than zero — and in recent versions that is already on, defaulting to 200. - Session
LISTEN/NOTIFY,WITH HOLDcursors 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.
| Scenario | max_connections per process | PgBouncer | What to monitor |
|---|---|---|---|
| Monolithic Puma, one process, 5 threads | 5, matching RAILS_MAX_THREADS | No, unless the Postgres ceiling is already tight | checkout_wait on primary; pg_stat_activity |
| Falcon with fibers | Start at 5–15, not at peak fibers; isolation_level = :fiber and permanent checkout :disallowed | Only if many workers push the total up | checkout_wait duration and connections held until the request ends |
| Pitchfork, many workers | 1 or 2 per worker | Yes, when workers × replicas approach the ceiling | Total Postgres connections at peak and during deploys |
| Kamal with several replicas | The same per process, multiplied by replicas, with headroom for deploy overlap | Yes, when that sum approaches the RDS ceiling | Total connections against the server's max_connections |
| Solid Queue on the same Postgres | queue pool equal to worker concurrency, plus the primary that jobs also use | Transaction mode is fine: Solid Queue uses FOR UPDATE SKIP LOCKED | checkout_wait on queue and primary, separately |
| RDS with a low ceiling | Small, explicit pools on each Solid Trio database | Yes, transaction mode | The 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
- This Week in Rails: November 6, 2026 rubyonrails.org
- Rails Guides: Active Support Instrumentation guides.rubyonrails.org
- Rails Guides: Configuring Rails Applications — database pooling guides.rubyonrails.org
- ActiveRecord::ConnectionAdapters::ConnectionPool (Rails 8.1) api.rubyonrails.org
- Rails Guides: Multiple Databases with Active Record guides.rubyonrails.org
- rails/solid_queue github.com
- PgBouncer: Features www.pgbouncer.org
- PostgreSQL: Connection and Authentication www.postgresql.org
- 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.