---
title: "Fit the connection budget to the · Agent Wranglers"
url: https://agentwranglers.se/playbook/scaling/growing-the-database/connection-budget
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Fit the connection budget to the autoscaling maximum

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Growing the database](https://agentwranglers.se/playbook/scaling/growing-the-database.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: SCL-23
- Level: Required
- Chapter: [Growing the database](https://agentwranglers.se/playbook/scaling/growing-the-database)
- Rule: The maximum number of copies of each process type times its pool size, summed over all types, stays below the database's connection limit. Check it whenever a maximum or a pool size changes.
- Risk: The app down or unusable
- Applies when: The project runs its own servers, virtual machines or containers.
- How: PostgreSQL's `max_connections` is typically 100 by default, and 3 of those are kept for superusers. Autoscaling to 20 copies with a pool of 10 asks for 200. New copies then fail to connect just at the peak they were started for. [Pool database connections](https://agentwranglers.se/playbook/data/operations/connection-pooling) sets the rule for one process. When the sum is too high, put a pooler in front, as [the PgBouncer pick](https://agentwranglers.se/playbook/stack/databases-and-storage/pgbouncer) explains. Count web, worker and scheduled processes, and leave 10% free for migrations and people.
- Check: A test in CI reads the deploy settings and sums the maximum copies times the pool size for every process type. The sum is at most 90% of `max_connections` minus the reserved connections.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
import { test } from 'node:test';
import assert from 'node:assert/strict';
import settings from '../deploy/settings.json' with { type: 'json' };

const SHARE_FOR_APPS = 0.9;

test('pools fit the database connection limit', () => {
  const wanted = settings.processes.reduce((sum, p) => sum + p.maxCopies * p.poolSize, 0);
  const usable = settings.database.maxConnections - settings.database.reservedConnections;
  assert.ok(wanted <= usable * SHARE_FOR_APPS, `${wanted} connections wanted, ${usable} usable`);
});
```

### Python example

```python
import json

SHARE_FOR_APPS = 0.9

def test_pools_fit_the_database_connection_limit():
    settings = json.load(open("deploy/settings.json"))
    wanted = sum(p["maxCopies"] * p["poolSize"] for p in settings["processes"])
    db = settings["database"]
    usable = db["maxConnections"] - db["reservedConnections"]
    assert wanted <= usable * SHARE_FOR_APPS, f"{wanted} connections wanted, {usable} usable"
```

## Sources

- [PostgreSQL connection settings](https://www.postgresql.org/docs/current/runtime-config-connection.html)

## Related rules

- [Size workers and pools from rate times duration](https://agentwranglers.se/playbook/scaling/measure-before-you-scale/size-from-rate-and-duration) in Scaling
- [Pool database connections](https://agentwranglers.se/playbook/data/operations/connection-pooling) in Data
- [Use PgBouncer when many app servers share PostgreSQL](https://agentwranglers.se/playbook/stack/databases-and-storage/pgbouncer) in Software choices
- [Scale on the resource that runs out](https://agentwranglers.se/playbook/scaling/load-balancing-and-autoscaling/scale-on-saturation) in Scaling

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/scaling/growing-the-database/connection-budget">Agent Wranglers scaling playbook</a>`. In code you write, add a comment next to it with the same link.

- Next: [Keep reports and exports off the primary](https://agentwranglers.se/playbook/scaling/growing-the-database/reports-off-primary)
- [Growing the database](https://agentwranglers.se/playbook/scaling/growing-the-database)