What is database connection pool sizing, and why is max_connections a hard ceiling?

Database connection pool sizing is the work of deciding how many connections each process in your application may hold open, so that the total across every process stays under what the database will accept. In a monolith with several process types, such as Puma web servers, Sidekiq workers, cron runners and one-off console sessions, all sharing one Postgres primary, each pool can't be sized on its own. Every pool draws from the same fixed budget, and the budget is set on the database side by max_connections.

That ceiling is hard for a structural reason. Postgres uses a process-per-connection model: every client connection gets its own backend operating system process with its own private memory. Idle backends still consume resources. Active ones can allocate memory up to work_mem for each sort or hash operation in a query, so a single complex query can use several multiples of it. Once the limit is reached, new connection attempts are refused with an error. They don't queue.

You also don't get the full number. A few slots are held back by superuser_reserved_connections so an administrator can still log in during an incident. Replication, backup tooling and monitoring agents take more slots.

Raising max_connections should be a last resort. It requires a server restart, and it multiplies worst-case memory use. Past roughly the number of CPU cores available for active work, more concurrent backends mostly add context switching and lock contention. Throughput can fall even though the database accepts more clients.

Who should use this approach?

Explicit, fleet-wide pool sizing is for teams running a Rails monolith in which several process types share one Postgres primary. The typical setup has Puma serving web traffic, Sidekiq running background jobs, and some combination of cron containers, release-phase migrations and console sessions. It matters most in these situations:

  • Containerized or autoscaled deployments. Replica counts change without anyone touching database.yml, so the number of pools changes too.
  • Managed Postgres with a fixed max_connections. The limit is often tied to the instance size. Running out of connections then pushes you toward a larger instance you may not otherwise need.
  • Teams already seeing symptoms. These include ActiveRecord::ConnectionTimeoutError in the application, Postgres refusing new connections (sorry, too many clients already), or failures that appear only during deploys or traffic spikes.
  • Teams that tune Sidekiq concurrency to drain backlogs. Every concurrency change is also a connection change.

A single small server with one Puma process and one Sidekiq process, far below the limit, needs much less of this. Do the arithmetic once and write it down. Revisit it when the topology grows.

How does connection pool sizing work?

The mechanism has three layers, and sizing means keeping them consistent with each other.

  1. Thread to pool. Inside one Ruby process, a thread that needs the database checks out a connection from that process's Active Record pool. It returns the connection when the request or job finishes, or when the code releases it. If every connection is checked out, the thread waits up to checkout_timeout and then raises ActiveRecord::ConnectionTimeoutError.
  2. Pool to backend. The pool opens connections lazily, up to its configured pool size. Each open connection is one Postgres backend process on the server. The pool size is therefore the most backends that one process can create.
  3. Backends to the server limit. Postgres counts every client backend from every process, container and tool against one max_connections value. It does not know or care which pool a connection came from.

The sizing process follows from those layers:

  1. Inventory every process type that connects, including the ones outside the main app such as cron, migrations, consoles and monitoring.
  2. Set each pool to the number of threads in that process that can touch the database.
  3. Multiply each pool by its process count and replica count at peak, including deploy surge, and add headroom.
  4. Compare the total with max_connections. If it doesn't fit, reduce threads or processes, or add a pooler. Don't just shrink pools.
  5. Enforce the result in configuration and CI, and monitor both the application pools and the server.

The sections below go through each step.

How do Puma and Sidekiq processes turn into Postgres connections?

Each Puma worker is a forked OS process, and Active Record connections cannot be shared across a fork. Every worker therefore builds its own pool after boot. Within a worker, each request thread checks out one connection for the duration of its database work. If the pool is smaller than the thread count, threads queue for a connection and eventually raise a checkout timeout. For that reason the pool should generally be at least the thread count. The pool is a ceiling, not a preallocation: connections open lazily. Under sustained load, though, plan for the ceiling. Web demand per container is workers × threads.

Sidekiq concurrency is a thread count inside a single process. The pool must cover that number, plus any threads your own code starts that also touch the database. Raising concurrency from 10 to 25 to drain a backlog adds 15 potential backends per process, multiplied by every Sidekiq replica.

Container A (Puma: 2 workers x 5 threads)     Container B (Sidekiq: concurrency 10)
 ├─ worker 1 ─ pool(5) ─┐                       └─ process ─ pool(10) ─┐
 └─ worker 2 ─ pool(5) ─┤                                              │
                        ▼                                              ▼
              Postgres: up to 10 backends          +        up to 10 backends

The GVL shapes the trade-off. Only one thread per Ruby process executes Ruby code at a time, and threads mostly help while others wait on I/O. Fewer workers with more threads saves both connections and memory. For CPU-bound work, those extra threads add contention rather than throughput.

production:
  adapter: postgresql
  url: <%= ENV["DATABASE_URL"] %>
  # Size the pool to the threads that can touch the DB in this process:
  #   Puma container:    RAILS_MAX_THREADS = Puma threads per worker (e.g. 5)
  #   Sidekiq container: RAILS_MAX_THREADS = Sidekiq concurrency (e.g. 10)
  # DB_POOL_EXTRA is an app-specific variable for threads your own code
  # starts that also use Active Record.
  pool: <%= ENV.fetch("RAILS_MAX_THREADS", 5).to_i + ENV.fetch("DB_POOL_EXTRA", 0).to_i %>
  # How long (seconds) a thread waits for a free connection before raising
  # ActiveRecord::ConnectionTimeoutError.
  checkout_timeout: 5

A database.yml that ties each process's Active Record pool to its thread count, with the arithmetic showing how Puma workers × threads and Sidekiq concurrency × replicas add up to Postgres backends.

How do you calculate total connection demand across the whole fleet?

Total demand is the sum, over every process type, of instances × processes per instance × pool size. Then add headroom for everything outside the pools: migrations, rails console sessions, cron jobs, monitoring agents, replication, and the slots Postgres keeps back for superusers (superuser_reserved_connections). That sum must stay below max_connections.

Illustrative estimate

Assumed inputs: max_connections = 200, Puma with 3 workers × 5 threads, Sidekiq with concurrency 10.

Process type Instances Processes each Pool size Connections
Puma web 6 3 5 90
Sidekiq 4 2 10 80
Headroom (consoles, cron, migrations, monitoring, reserved) — — — 25
Total 195

This fits, with 5 connections to spare. A better approach is to work downward from the ceiling. Subtract headroom first (200 − 25 = 175). Divide what remains between process types according to how many processes each one runs at peak. Then set each pool to match its thread or concurrency count. If the numbers don't fit, reduce threads per process. Shrinking the pool while leaving threads unchanged makes threads wait for connections and eventually time out.

Use peak figures for this calculation. Pool size is an upper bound, and connections open lazily, so a quiet process holds only a few. Average counts from monitoring therefore look reassuring. The real risk shows up when every thread is busy at the same moment, and averages hide those spikes.

Read replicas and multiple databases add to the total. Each process keeps a separate pool for every database it connects to. A process with a primary and one replica holds two pools, and each pool counts against its own server's limit.

Why do deploys and autoscaling break a connection budget that looks safe?

The transient peak

A rolling deploy starts new processes before it stops old ones. Old processes keep their pools open until they drain and exit, while new ones connect as soon as they boot. For the length of the rollout, the fleet holds more connections than either version uses alone. A horizontal autoscaler has the same blind spot: it scales on CPU or queue depth and never checks how many connections Postgres has left.

Budget for the peak, not the steady state:

peak = Σ over process types of (max_replicas + surge_replicas) × connections_per_replica

This must stay below max_connections minus a reserve for migrations, consoles and superuser access.

Illustrative estimate (assumed numbers, not a benchmark). Assume max_connections = 300 and a reserve of 20, which leaves 280. Each web replica runs 3 Puma workers with 5 threads, so it needs 15 connections. Sidekiq uses 4 replicas at concurrency 10, plus 1 surge replica, for 50 connections. Web surge is 25%. That leaves 230 for web, so the limit is web_max × 15 × 1.25 ≤ 230, which gives web_max ≤ 12. If the autoscaler's ceiling is set to 20, the fleet will exhaust connections under load during a deploy.

Budgets go stale

The calculation is only correct for the topology it was based on. Adding a new Sidekiq queue type, a cron container or more replicas changes the total, and nobody reruns the numbers. Give the budget an owner and put a check in CI. The check reads replica limits, surge settings and pool sizes from the deploy configuration, computes the peak and fails the build if it exceeds the limit. This takes the place of the recurring incident where the database refuses connections partway through a deploy.

How do you implement and monitor pool sizes in a Rails monolith?

One variable per process type

Make pool in database.yml read from the environment instead of a literal, for example pool: <%= ENV.fetch("DB_POOL") %>. Each process type sets its own value: web containers set DB_POOL equal to RAILS_MAX_THREADS, and Sidekiq containers set it equal to the Sidekiq concurrency setting. Derive both values from one variable in the deploy manifest so they cannot drift. Drift causes problems in both directions. If the pool is larger than the thread count, the unused slots still count toward your budget. If it is smaller, threads queue for a connection.

Set a distinct application_name per process type, such as web, sidekiq-default, or sidekiq-critical. You can do this through the PGAPPNAME environment variable, which libpq reads, or through an application_name key in database.yml. Without it, every backend looks the same on the server.

Watching both ends

On the database, group pg_stat_activity by application_name and state. That shows which process type holds connections and how many sit idle compared with active or idle in transaction. Alert when the total crosses a threshold below max_connections, such as 80%, so you have time to act before Postgres refuses connections.

In the application, ActiveRecord::Base.connection_pool.stat reports busy, idle, and waiting counts. Export these per process. A nonzero waiting count, or any ActiveRecord::ConnectionTimeoutError, means the pool is smaller than the work the process is doing.

The CI budget check uses the same DB_POOL values that production reads, so the check and runtime cannot disagree.

-- 1) Who holds connections, and in what state?
-- Relies on each process type setting a distinct application_name
-- (web, sidekiq-default, sidekiq-critical, ...).
SELECT
  coalesce(nullif(application_name, ''), '(unset)') AS application_name,
  state,
  count(*) AS connections
FROM pg_stat_activity
WHERE backend_type = 'client backend'  -- skip autovacuum, WAL writer, etc.
  AND datname = current_database()     -- only the app database
GROUP BY 1, 2
ORDER BY application_name, connections DESC;

-- 2) Total usage against the server limit, for alerting.
-- Fire an alert when pct_used crosses a threshold such as 80,
-- well before Postgres starts refusing new connections.
-- No datname filter here: max_connections is shared by every database
-- on the server, so this counts all client backends.
SELECT
  count(*) AS total_connections,
  current_setting('max_connections')::int AS max_connections,
  round(100.0 * count(*) / current_setting('max_connections')::int, 1) AS pct_used
FROM pg_stat_activity
WHERE backend_type = 'client backend';

Two pg_stat_activity queries: the first breaks down the app database's client connections by application_name and state, and the second compares the server-wide total against max_connections to drive a threshold alert.

How can disciplined pool sizing save engineering time?

Most of the time spent on connection problems goes into diagnosis and repeated firefighting, not the fix itself. An explicit budget reduces both.

  • Fewer incident investigations. Connection exhaustion often shows up indirectly, as request timeouts, failed jobs or a deploy that stalls halfway. When the budget is written down and checked in CI, a change that would exceed it fails before it reaches production. Nobody has to reconstruct the cause from logs afterwards.
  • Faster diagnosis when something does go wrong. Distinct application_name values and exported pool stat counts turn "the database is full" into "the sidekiq-default replicas hold most of the backends and their pools are waiting". That narrows the investigation to one process type.
  • No trial-and-error tuning. Without the arithmetic, teams adjust pool, thread counts and Sidekiq concurrency by feel and wait to see what breaks. With it, the effect of a change, such as raising concurrency to drain a backlog, can be computed before the deploy.
  • Shorter capacity discussions. The calculation shows whether a larger database instance, a pooler or a code change is actually needed. This avoids buying a bigger instance only for its higher connection limit when the real cause is oversized pools or connections held during HTTP calls.
  • Safer configuration changes by people outside the original team. Because pool sizes derive from one variable per process type and the CI check reads the same values, someone adding a cron container or a new queue gets immediate feedback. They don't need to know the history of the database's limits.

The upfront cost is a small amount of configuration, a CI script and a dashboard. The ongoing cost is a review whenever the topology changes. Weigh that against how often your team currently loses time to connection-related incidents. That frequency is specific to your system, so measure it rather than assume it.

When should you avoid tight pool sizing, and what does it cost?

A pool sized exactly to the thread count assumes each thread holds a connection only briefly. That assumption breaks when code keeps a connection checked out while it waits on something else. Examples include an external HTTP call inside a transaction block, a job that streams a large export, or a long-running report query. A thread in that state is not using the database, but the connection is still unavailable to other threads, so those threads wait and eventually raise checkout timeouts. If your code does this, tight sizing turns slow upstream services into database errors.

Lowering Sidekiq concurrency to fit the budget has a direct cost in queue latency.

Illustrative estimate (assumed numbers, not a benchmark): drain time = backlog ÷ (concurrency ÷ average job seconds). With a 600-job burst and 2-second jobs, 10 threads drain the queue in 600 ÷ (10 ÷ 2) = 120 s. With 5 threads it takes 240 s.

Choice Benefit Cost
Pool = thread count Smallest connection footprint Timeouts when connections are held long
Lower Sidekiq concurrency Frees connections Higher queue latency
Separate processes per queue Slow queues can't starve fast ones Each process adds a pool to the budget
Pool headroom above threads Absorbs held connections Uses budget on connections that sit idle

Keeping the budget accurate takes ongoing work. Every new process type or concurrency change needs a review. Compare that cost against a single incident where max_connections is exhausted during a deploy.

The cheapest fix is often in the code. Move HTTP calls outside transactions. Batch long jobs into short units. Release connections explicitly before waiting on I/O.

What are the alternatives, and when should you use PgBouncer transaction pooling?

When code fixes are not enough, there are five levers. They differ in what they actually change:

Option What it changes Main cost
Raise max_connections The ceiling Memory per backend, more contention
Tighten pools Demand per process Checkout waits under bursts
Fewer processes, more threads Process count Less isolation, GVL contention
Read replicas Spreads reads Replication lag, routing logic
PgBouncer transaction mode Separates client connections from backends Extra hop, new failure point, fewer session features

Without a pooler, every application pool is sized for its own peak. Most of those backends sit idle most of the time, and the idle share grows with each process you add. PgBouncer in transaction mode assigns a server connection only for the length of a transaction. Thousands of client connections can then share a small, fixed set of Postgres backends.

The trade-off is that consecutive transactions from one client can run on different backends. Anything tied to a session needs care:

  • SET leaks to other clients or disappears. Use SET LOCAL inside a transaction.
  • Session advisory locks attach to the wrong backend. Use pg_advisory_xact_lock.
  • Prepared statements fail unless your pooler version supports them. Otherwise, disable them in Rails.
  • LISTEN/NOTIFY needs a direct connection.

Adopt a pooler when three things are true: summed peak pools exceed what Postgres can safely hold, measured backend utilization is low, and you have already fixed long transactions in code. Run it redundantly so it does not become a single point of failure.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to database connection pool sizing, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.