---
title: "How rolling deployments change your PostgreSQL connection budget | Proofline"
description: "A rolling deployment can exhaust PostgreSQL connections even when the running service fits. The connection budget must account for old and new tasks overlapping."
url: https://proofline.sh/learn/connection-limits/
---

[Learning center](/learn/)

# 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.

Capacity overruns The Proofline team November 5, 2026 8 min read

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](/integrations/aws-ecs/) service. Each task runs one application process with one pool connected directly to PostgreSQL:

| Setting | Value |
| --- | --- |
| Desired task count | 8 |
| Maximum connections per pool | 20 |
| PostgreSQL `max_connections` | 200 |
| Connections reserved for superusers | 3 |
| Additional reserved connections | 0 |
| Connections used by other clients | 20 |

The database has 197 slots available to ordinary clients after its three superuser reservations. The [PostgreSQL connection settings](https://www.postgresql.org/docs/18/runtime-config-connection.html) 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-ecs.html) 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 pools | API connections | Other clients | Total demand |
| --- | --- | --- | --- |
| 8 | 160 | 20 | 180 |
| 9 | 180 | 20 | 200 |
| 16 | 320 | 20 | 340 |

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](https://node-postgres.com/apis/pool).

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](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy-pinning.html) 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](https://proofline.sh/code-review/) 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](/learn/database-migration-review/). To assess Proofline on your team's pull requests, follow the [free code-review evaluation guide](/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](/free-code-review/).

[Start free with GitHub](https://proofline.sh/orgs/plan?offer=free150)

## Related reading

-   ### [AI code review for AWS](/blog/aws-deployment-review/)
    
    Deployment failures The Proofline team October 7, 2026 2 min read
    
-   ### [PostgreSQL migration review for rolling deployments](/learn/database-migration-review/)
    
    Breaking migrations The Proofline team October 7, 2026 6 min read
