“Too many clients”错误根源是PostgreSQL服务端max_connections耗尽或连接未归还，而非驱动版本问题；需优先检查并协同调优Hyperf连接池的max_connections（建议≤DB侧限制的70%）与wait_timeout（生产环境≥5.0秒），同时确认pgsql扩展已启用、包已正确安装且连接参数符合PostgreSQL规范。
Hyperf 连接 PostgreSQL 报 “致命错误：已经有太多的客户”，核心不是驱动版本问题，而是连接池配置与数据库侧限制严重不匹配——先查 max_connections 和 wait_timeout，再看驱动是否被误降级。
为什么“Too many clients”错误几乎从不源于驱动版本
这个错误（org.postgresql.util.PSQLException: 致命错误: 对不起, 已经有太多的客户）是 PostgreSQL 服务端明确拒绝新连接的信号，源头在 postgresql.conf 的 max_connections 值被耗尽，或客户端连接池未及时归还连接。Hyperf 的 pgsql 驱动（hyperf/database-pgsql）只要不低于 v3.0（对应 PHP 8.1+、PostgreSQL 协议 v3），就不会因协议兼容性触发该错误；盲目升级驱动反而可能引入协程调度 bug（如 2.2 → 3.0 升级后出现的 aio_thread failed）。
常见误判场景：
- 看到报错里有
postgresql-42.5.0.jar就以为是 Java 驱动问题 —— 但 Hyperf 用的是 PHP 原生扩展或 PDO，.jar文件根本不会加载 - 升级了
ext-pgsql扩展版本，却没重启 PHP-FPM 或 Swoole Worker，导致旧版本仍在运行 - 误将 MySQL 的
wait_timeout参数和 PostgreSQL 的tcp_keepalives_idle混为一谈
必须立刻检查的两个连接池参数
Hyperf 的 PostgreSQL 连接池中，max_connections 和 wait_timeout 是联动生效的。配错时，错误现象高度相似，但根因相反：
- 只调大
max_connections（比如设成 200），但wait_timeout还是 2.0 → 请求排队超时，日志满屏wait timeout，而SHOW PROCESSLIST看不到堆积连接（因为根本连不上库） - 只调大
wait_timeout（比如设成 10.0），但max_connections还是默认 10 → 连接池长期 busy > 90%，MySQL/PostgreSQL 侧出现Too many connections，hyperf_db_pool_used_connections指标峰值贴着上限跑
PostgreSQL 实际限制需同步确认：
- 查当前 DB 限制：
SHOW VARIABLES LIKE 'max_connections';（MySQL 语法，PostgreSQL 应用SHOW max_connections;） - 阿里云 PolarDB for PostgreSQL 默认最大连接数按规格浮动（如 4 核 16 GB 是 500），不是本地 100
- Hyperf 的
max_connections建议 ≤ DB 侧限制的 70%，预留空间给备份、监控、DBA 临时连接
PostgreSQL 连接池配置示例与避坑点
在 config/autoload/databases.php 中，PostgreSQL 连接池应显式声明关键参数，不能依赖默认值：
'default' => [
'driver' => 'pgsql',
'host' => env('DB_HOST', 'localhost'),
'port' => (int) env('DB_PORT', 5432),
'database' => env('DB_DATABASE', 'forge'),
'username' => env('DB_USERNAME', 'forge'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8',
'schema' => 'public',
'pool' => [
'min_connections' => 1,
'max_connections' => (int) env('DB_POOL_MAX', 80), // 生产环境建议 60–80
'connect_timeout' => 10.0,
'wait_timeout' => 5.0, // 生产必须 ≥ 5.0，开发最低 2.5
'max_idle_time' => 60.0,
'heartbeat' => -1,
],
],
容易被忽略的细节：
-
wait_timeout是 Hyperf 连接池自己的等待策略，和 PostgreSQL 的tcp_keepalives_idle、idle_in_transaction_session_timeout完全无关 - 多 Schema 场景下，不要为每个 Schema 单独配一个连接池（如
tenant_a、tenant_b），而应在运行时通过SET search_path TO schema_name切换，否则池子数量翻倍，极易打穿 DB 限制 - Redis 连接池必须单独配
max_connections，和 PostgreSQL 池互不干扰；共用同一数值会导致资源争抢，引发No available connection
真要查驱动，只盯这三个地方
如果排除了连接池和 DB 限制，仍怀疑驱动问题，只需验证以下三点：
- PHP 是否启用
pgsql扩展：php -m | grep pgsql，没输出就说明扩展未加载 - Hyperf 项目是否安装了
hyperf/database-pgsql包：composer show hyperf/database-pgsql，v3.x 要求 PHP ≥ 8.1，v2.x 支持 PHP 7.4–8.0 - 连接字符串是否误加了 MySQL 风格参数，如
charset=utf8mb4（PostgreSQL 应用client_encoding=utf8）
驱动本身极少导致 “Too many clients”，但配置错、扩展没装、包没装对，会把问题伪装成连接数爆满——本质是连接根本没建成功，还在反复重试占位。
