Learning center

How rolling deployments change your PostgreSQL connection budget

A rolling deployment can exhaust PostgreSQL connections even when the running service fits. The connection budget must account for old and new tasks overlapping.

If a rollout produces remaining connection slots are reserved for roles with the SUPERUSER attribute, count connections from both revisions before raising max_connections. Include every process and pool, reserved slots and other database clients. The example below calculates the budget, reproduces PostgreSQL's slot limit and compares pool, rollout and proxy tradeoffs.

Steady-state connection math#

Consider an illustrative Amazon ECS service. Each task runs one application process with one pool connected directly to PostgreSQL:

SettingValue
Desired task count8
Maximum connections per pool20
PostgreSQL max_connections200
Connections reserved for superusers3
Additional reserved connections0
Connections used by other clients20

The database has 197 slots available to ordinary clients after its three superuser reservations. The PostgreSQL connection settings also allow additional reserved slots; this example sets those to zero.

Eight full pools use 160 connections. Background workers, scheduled jobs and operational tools hold another 20 throughout the deployment. Total demand is 180, leaving 17 slots. One additional full pool needs 20.

How rolling deployments multiply connection demand#

The service uses this rolling deployment configuration excerpt:

desired_count = 8

deployment_minimum_healthy_percent = 100
deployment_maximum_percent        = 200

ECS must keep eight healthy tasks and can hold up to 16 tasks in RUNNING or PENDING states during the rollout. The ECS rolling deployment documentation describes the scheduling limits and rounding rules. The 16-task ceiling includes pending tasks, so it does not establish how many processes connect to PostgreSQL.

If each running application process fills its pool, demand looks like this:

Application tasks with full poolsAPI connectionsOther clientsTotal demand
816020180
918020200
1632020340

Under these assumptions, the first replacement task can exceed the connection budget. PostgreSQL admits at most 197 ordinary-client connections, so the larger totals represent demand for slots the database cannot provide. The service need not reach its rollout ceiling to encounter that limit.

Eager pool warmup vs. lazy connection allocation#

A configured pool maximum does not allocate every connection at startup. For example, node-postgres pools start empty and grow as clients are needed.

A stalled rollout requires additional conditions. Suppose all eight old tasks retain full pools, other clients retain 20 connections, and a replacement must establish all 20 connections before its health check passes. Only 17 slots remain. The replacement cannot finish warmup, and the 100-percent healthy minimum prevents ECS from stopping a healthy old task first. A configured deployment circuit breaker may eventually fail or roll back the deployment.

A lazy pool can pass a lightweight health check with zero or one database connection. That lets replacement proceed, but connection demand can still exceed the budget while revisions overlap under traffic. New connection attempts may fail during requests. Check pool initialization, connection retention and health-check behavior before predicting either outcome.

Reproducing the PostgreSQL connection limit#

A small database-only test makes the slot limit observable. On an isolated PostgreSQL 18.6 instance, the probe held 180 ordinary-client connections open and attempted 20 more. Both runs accepted 17 and rejected three. A query through an existing connection counted 197 application connections in pg_stat_activity.

To repeat the probe, use a dedicated PostgreSQL 18 instance with the settings in the table and no other clients. Create an ordinary login role, then close the administrator connection:

CREATE ROLE budget_app LOGIN;

Install Psycopg 3 with python -m pip install "psycopg[binary]" in a virtual environment. Set PGHOST and PGPORT for that instance, and configure local authentication for budget_app. The probe uses the postgres database. Run:

from contextlib import ExitStack
import psycopg

with ExitStack() as clients:
    def connect():
        return clients.enter_context(
            psycopg.connect(dbname="postgres", user="budget_app", connect_timeout=5)
        )

    baseline = [connect() for _ in range(180)]
    print(f"Baseline connections held: {len(baseline)}")
    accepted, rejected, first_error = 0, 0, None
    for _ in range(20):
        try:
            connect()
            accepted += 1
        except psycopg.OperationalError as error:
            rejected += 1
            if first_error is None:
                first_error = str(error).splitlines()[-1]
    print(f"Replacement attempts: accepted={accepted}, rejected={rejected}")
    with baseline[0].cursor() as cursor:
        cursor.execute("SELECT count(*) FROM pg_stat_activity WHERE usename = 'budget_app' AND backend_type = 'client backend'")
        print(f"Observed application connections: {cursor.fetchone()[0]}")
    print(first_error)

The rejected attempts reported remaining connection slots are reserved for roles with the SUPERUSER attribute. The context manager closes the held connections when the probe exits.

This experiment holds otherwise idle database sessions open. It establishes PostgreSQL's admission behavior for this configuration. It does not run ECS, exercise an application pool, or measure rollout reliability. Those require a separate deployment experiment.

Calculating the upper-bound budget for overlapping revisions#

Count the old and new revisions separately:

API connection demand =
    old tasks × pools per old task × old pool maximum
  + new tasks × pools per new task × new pool maximum

Total demand =
    API connection demand
  + other database clients

Keep the revisions separate when a change adjusts pool limits or worker counts, because each task may then request a different number of connections. Four worker processes with one 20-connection pool each can request 80 connections per task.

When both revisions use identical settings, the check simplifies to:

peak tasks × pools per task × pool maximum
    + other clients
    + operating headroom
    ≤ usable database connections

This addresses slot availability. CPU, memory and I/O can still limit the queries those connections execute.

The following calculator checks the illustrative configuration's upper bound:

from math import floor

desired_tasks = 8
maximum_percent = 200
pools_per_task = 1
pool_maximum = 20

usable_connections = 200 - 3
other_clients = 20

peak_tasks = floor(desired_tasks * maximum_percent / 100)
demand = peak_tasks * pools_per_task * pool_maximum + other_clients

print(f"Task ceiling: {peak_tasks}")
print(f"Connection demand at full pools: {demand}")
print(f"Usable connections: {usable_connections}")
print(f"Headroom: {usable_connections - demand}")

Its output is:

Task ceiling: 16
Connection demand at full pools: 340
Usable connections: 197
Headroom: -143

The negative headroom shows that the configured pools can request more slots than the database provides. To establish how close actual demand comes to that ceiling, observe connections during a deployment window.

Tradeoffs when adjusting pools, rollout percentages, and proxies#

Pool size and deployment_maximum_percent#

A pool maximum of 12 and deployment_maximum_percent of 150 allow up to 12 tasks:

12 tasks × 12 connections + 20 other clients = 164

That leaves 33 slots within the 197-slot budget. This assumes both revisions already use twelve-connection pools. The rollout introducing that setting must still count old tasks with twenty-connection pools separately.

Smaller pools can increase query wait times when demand exceeds the available connections. Load testing can establish whether that queueing stays acceptable under the tested workload.

Reducing only the rollout maximum to 125 percent allows up to 10 tasks:

10 tasks × 20 connections + 20 other clients = 220

That still exceeds the budget with full 20-connection pools.

Scheduler rounding and deployment_minimum_healthy_percent#

ECS rounds the maximum task count down and the minimum healthy count up. At eight desired tasks, a maximum of 112 percent permits eight tasks (floor(8 * 1.12) = 8). A minimum of 100 percent requires eight healthy tasks. With all eight old tasks healthy, ECS can neither start a ninth task nor stop an old task first.

A minimum of 99 percent still rounds up to eight. Lower it enough to permit seven healthy tasks and a stop-first rollout becomes possible, at the cost of serving capacity. The remaining tasks must handle the traffic.

Connection proxies and max_connections#

Amazon RDS Proxy can let multiple application connections share fewer database connections. Session pinning reserves a backend connection until the client session ends. An active transaction also occupies a backend until it finishes. Measure backend connection counts and pinning under representative traffic before budgeting for multiplexing.

Raising max_connections increases resources PostgreSQL allocates for connections. More active queries can also increase CPU, memory and I/O contention. Additional slots need a database capacity check.

What to verify before deploying a pool or scaling change#

For a pull request changing task counts, worker processes, pool limits or deployment parameters, collect:

  • Process and pool counts, pool maxima and connection-retention behavior for both revisions.
  • ECS desired count and rollout percentages, including integer rounding.
  • Database connection limits, reservations and demand from every other client.
  • Startup warmup requirements and the health check's database dependencies.
  • Concurrent task counts, database connections and pool wait times during deployment windows.

Use configuration to calculate the bound and telemetry to observe usage within its recorded window. A quiet-period snapshot cannot establish demand during a rollout.

Connecting code and environment facts in Proofline#

Proofline reviews exact code revisions against evidence from the target environment. This budget illustrates why both inputs matter: pool settings and process counts come from application code, while the running revision, rollout settings and shared database capacity must be checked against the target environment. A useful finding cites the inputs behind its calculation and identifies missing evidence.

When the same release changes the schema, also review PostgreSQL migration compatibility across running versions. To assess Proofline on your team's pull requests, follow the free code-review evaluation guide.

Questions#

Why do PostgreSQL connections run out during a rolling deployment?

Old and new application processes can hold connections at the same time. Their combined demand, plus other database clients and reserved slots, can exceed the database limit even when either revision fits on its own. Calculate both revisions separately when pool sizes or process counts change.

Does increasing max_connections fix a failed deployment?

It can provide more slots, but it also increases PostgreSQL's resource allocation. Active queries can increase CPU, memory and I/O contention too. Check database capacity and the rollout's connection demand before choosing a larger limit.

Can RDS Proxy reduce the connections needed during a rollout?

It can let application connections share fewer database connections. Transactions and session pinning can limit that sharing. Measure backend connections and pinning under representative traffic before relying on multiplexing in the budget.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading