# max_connections

> The startup-time ceiling on concurrent PostgreSQL client connections and a sizing input for several shared resources.
---

> [!NOTE]
> **Fact — official short description:** “Sets the maximum number of concurrent connections.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `integer` | Upstream pg_settings type |
| Context | `postmaster` | Requires a server restart |
| Unit | — | Raw unit |
| Range | `1` – `262143` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Connections and Authentication / Connection Settings | Upstream classification |
| Latest boot value | `100` | 100 |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG9.0–19 Beta 3 | `100` | — | 100 |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

max_connections limits concurrent database-server connections and can only be changed at server start. PostgreSQL sizes some resources directly from it, so raising the ceiling increases allocations including shared memory even when not all slots are busy.

reserved_connections and superuser_reserved_connections carve emergency or privileged capacity out of the same overall ceiling. An application therefore cannot normally consume every configured slot.

A standby must use a value at least as high as its primary. Connection pooling can decouple large client populations from a smaller, controlled number of PostgreSQL backends.

## Tuning advice {#tuning-advice}

> [!TIP]
> **Advice.** These are workload-specific starting points and must be validated with measurements.

| Workload | Guidance |
| --- | --- |
| OLTP | Prefer transaction pooling for large client populations and size PostgreSQL backends for peak active database work plus monitoring, maintenance, and failover margin. Do not map one client connection to one server slot by default. |
| OLAP | Analytical sessions are usually fewer and heavier; keep the backend ceiling low enough that simultaneous work_mem and parallel-worker demand remain bounded. Reserve explicit capacity for ETL and administration. |
| Small nodes | Use a low ceiling with a pooler and preserve reserved slots. Validate startup shared-memory requirements and do not compensate for connection leaks by repeatedly raising the limit. |
{.full-width}

## Pigsty {#pigsty}

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

| Template | Effective value | Versus upstream boot | Source expression |
| --- | --- | --- | --- |
| OLTP | `500` | different | `{{ pg_max_connections }}` |
| OLAP | `500` | different | `{{ pg_max_connections }}` |
| CRIT | `500` | different | `{{ pg_max_connections }}` |
| TINY | `250` | different | `{{ pg_max_connections }}` |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 500 (dcs); OLAP: PG9.0–19 Beta 3 = 500 (dcs); CRIT: PG9.0–19 Beta 3 = 500 (dcs); TINY: PG9.0–19 Beta 3 = 250 (dcs). Advice, pending human review — Editorial inference: the templates expose a generous compatibility ceiling behind pooling while reducing it for the small-node profile, but actual active-backend and memory limits still need workload-specific review.

## Common pitfalls {#common-pitfalls}

- Changing the value without planning a restart and keeping standbys at least as high as the primary.
- Ignoring shared-memory and per-backend overhead created by a higher ceiling.
- Forgetting reserved and superuser-reserved slots when calculating application capacity.
- Combining a high connection ceiling with generous per-operation memory settings and assuming the product cannot occur.

## Related parameters {#related-parameters}

[`reserved_connections`](/parameters/reserved-connections/) · [`superuser_reserved_connections`](/parameters/superuser-reserved-connections/) · [`work_mem`](/parameters/work-mem/) · [`max_worker_processes`](/parameters/max-worker-processes/) · [`max_prepared_transactions`](/parameters/max-prepared-transactions/) · [`max_wal_senders`](/parameters/max-wal-senders/)

## References {#references}

- [PostgreSQL 19 Beta 3 — max_connections](https://www.postgresql.org/docs/19/runtime-config-connection.html#GUC-MAX-CONNECTIONS)
- [Pigsty: Parameter Templates](https://pigsty.io/docs/pgsql/template/)
- [Pigsty: Parameter Optimization Policy](https://pigsty.io/docs/pgsql/template/tune/)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)