# max_connections

> PostgreSQL 客户端并发连接的启动时上限，也是多项共享资源的尺寸输入。
---

> [!NOTE]
> **Fact — 官方简述译文**：设置数据库并发连接的最大数量。

## 身份 {#identity}

| 字段 | 值 | 含义 |
| --- | --- | --- |
| 类型 | `integer` | 上游 pg_settings 类型 |
| Context | `postmaster` | 修改后需要重启数据库 |
| 单位 | — | 原始单位 |
| 范围 | `1` – `262143` | 最后在档版本的原始上下限 |
| 枚举值 | — | 非枚举类型记为 — |
| 分类 | Connections and Authentication / Connection Settings | 上游分类 |
| 最后 boot 值 | `100` | 100 |
{.fields meta="-"}

## 生命周期 {#lifecycle}

| Fact | 值 |
| --- | --- |
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |

## 默认值变迁 {#default-history}

| 版本 | 原始 `boot_val` | 单位 | 人类可读值 |
| --- | --- | --- | --- |
| PG9.0–19 Beta 3 | `100` | — | 100 |
{.full-width caption="PG9.0–19 Beta 3 实测 boot 默认值"}

## 机制详解 {#mechanism}

max_connections 限制数据库服务器的并发连接数，只能在服务器启动时修改。PostgreSQL 会直接按该值确定部分资源规模，因此即使连接槽未全部使用，调高上限也会增加包括共享内存在内的分配。

reserved_connections 与 superuser_reserved_connections 从同一个总上限中划出应急或特权容量，因此普通应用通常不能占满所有配置槽位。

备用库的取值必须不低于主库。连接池可以把大量客户端连接与较少、受控的 PostgreSQL 后端连接解耦。

## 调优建议 {#tuning-advice}

> [!TIP]
> **Advice。** 以下建议是工作负载起点，必须用真实测量验证。

| 场景 | 建议 |
| --- | --- |
| OLTP | 面对大量客户端时优先使用事务池，按峰值活跃数据库工作量，加上监控、维护和故障转移余量来确定后端数；不要默认把每个客户端连接映射为一个服务器槽位。 |
| OLAP | 分析会话通常更少但更重，应把后端上限控制在能约束 work_mem 与并行工作进程总需求的范围，并为 ETL 与管理预留明确容量。 |
| 小规格 | 使用较低上限配合连接池并保留应急槽位。验证启动所需共享内存，不要通过不断提高上限掩盖连接泄漏。 |
{.full-width}

## Pigsty 取值 {#pigsty}

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
| --- | --- | --- | --- |
| OLTP | `500` | 不同于 boot 值 | `{{ pg_max_connections }}` |
| OLAP | `500` | 不同于 boot 值 | `{{ pg_max_connections }}` |
| CRIT | `500` | 不同于 boot 值 | `{{ pg_max_connections }}` |
| TINY | `250` | 不同于 boot 值 | `{{ pg_max_connections }}` |
{.full-width}

> [!CAUTION]
> **Advice — 待人工复核。** 当前 Pigsty 模板投影事实：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)。 建议（待人工复核）——编辑推断：模板在连接池后提供较宽松的兼容性上限，并为小节点降低上限，但实际活跃后端数与内存边界仍需按负载复核。

## 常见坑 {#common-pitfalls}

- 修改后没有安排重启，也没有保证备用库取值至少与主库相同。
- 忽略更高连接上限带来的共享内存与每后端开销。
- 计算应用容量时忘记预留连接与超级用户预留槽。
- 同时使用很高的连接上限和宽松的单操作内存，却认为二者不会相乘。

## 关联参数 {#related-parameters}

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

## 参考资料 {#references}

- [PostgreSQL 19 Beta 3 — max_connections](https://www.postgresql.org/docs/19/runtime-config-connection.html#GUC-MAX-CONNECTIONS)
- [Pigsty：参数模板](https://pigsty.io/docs/pgsql/template/)
- [Pigsty：参数优化策略](https://pigsty.io/docs/pgsql/template/tune/)
- [PostgreSQL 19 发行说明](https://www.postgresql.org/docs/19/release-19.html)
- [机器可读 GUC 全量导出](/data/guc.jsonl)