hyperf数据库连接池需显式启用并合理配置：在databases.php中设enable_pool=true，min_connections=5～10，max_connections=20～100，配合env变量动态管理，多库/redis须独立配置，通过metrics监控验证复用效果。
如果您在 Hyperf 项目中遇到数据库响应延迟、连接频繁创建销毁或高并发下报“No available connection”错误，则很可能是数据库连接池未启用或配置不合理。以下是配置 Hyperf 数据库连接池的具体方法：
一、启用连接池并设置基础参数
Hyperf 的数据库连接池并非默认开启，必须显式启用并配置大小范围，否则所有 DB 操作将退化为每次新建 PDO 连接，严重拖慢性能。配置需在 config/autoload/databases.php 中完成，针对每个数据库连接定义 pool 子项。
1、打开 config/autoload/databases.php 文件，定位到目标连接（如 default）的配置数组内部。
2、在该连接配置中添加 pool 键，并确保其值包含 min_connections 和 max_connections 字段。
3、将 enable_pool 显式设为 true（注意：Hyperf v3.0+ 默认仍为 false，不可省略）。
4、示例配置片段如下：
'pool' => ['enable_pool' => true, 'min_connections' => 5, 'max_connections' => 50, 'wait_timeout' => 3.0, 'heartbeat' => -1]。
二、通过环境变量动态控制连接池参数
为适配不同部署环境（开发/测试/生产），应避免硬编码连接池数值，改用 .env 文件驱动配置。Hyperf 的 env() 函数可安全读取并转换类型，防止整数被误解析为字符串。
1、在项目根目录的 .env 文件中添加以下行：
DB_POOL_MIN=5
DB_POOL_MAX=80
DB_POOL_WAIT_TIMEOUT=3.0。
2、修改 config/autoload/databases.php 中对应连接的 pool 配置，使用 env() 替换固定值：
'min_connections' => (int) env('DB_POOL_MIN', 1),
'max_connections' => (int) env('DB_POOL_MAX', 20),
'wait_timeout' => (float) env('DB_POOL_WAIT_TIMEOUT', 3.0)。
3、保存后重启服务，确保环境变量生效且类型正确转换。
三、独立配置 Redis 连接池以解耦资源
当项目同时使用 MySQL 与 Redis 时，二者连接池必须完全分离，共用同一池参数会导致争抢、超时或指标混淆。Redis 连接池配置位于 config/autoload/redis.php，其结构与数据库池类似但作用域独立。
1、确认 config/autoload/redis.php 已存在且已启用（通常由 hyperf/redis 组件自动注册）。
Hyperf 3.2.3于2026年7月30日发布，是3.2分支的官方维护版本，新增支持函数，并修复模型注释、缓存组件文档、数据库模型构建器注释和关联预加载字段等问题。
2、为每个 Redis 连接（如 default、cache、queue）分别配置 pool 子项，禁止复用 MySQL 的 max_connections 值。
3、关键参数必须差异化设定：例如 cache 连接池可设 min_connections => 2、max_connections => 20；而 queue 因写入密集，建议设 min_connections => 5、max_connections => 30。
4、检查 pool.wait_timeout 是否统一设为 3.0，避免某类连接长期阻塞协程。
四、运行时热更新连接池配置（无需重启）
对于需动态增删数据库实例的 SaaS 多租户场景，无法依赖静态配置文件。此时可通过监听框架事件，在 Worker 启动后注入新连接池定义，实现配置热加载。
1、创建服务类 App\Service\DynamicDbPoolService，注入 Hyperf\Contract\ConfigInterface。
2、在服务方法中调用 $config->get('databases') 获取当前全部连接配置，以 default 为模板克隆新连接数组，修改 database、host 等字段。
3、调用 $config->set('databases', $mergedArray) 将新连接合并进全局配置。
4、绑定该服务至 Hyperf\Framework\Event\AfterWorkerStart 事件监听器，确保每个 Worker 进程启动时均执行一次注入。
五、验证连接池是否生效
仅修改配置不等于连接池已工作，必须通过监控指标或日志确认连接是否真正来自池化管理，而非每次 new PDO。
1、启用 Hyperf 内置 Metrics：在 config/autoload/metrics.php 中开启 db.pool 指标采集。
2、部署 Prometheus + Grafana，查看 hyperf_db_pool_used_connections 与 hyperf_db_pool_idle_connections 实时曲线是否随请求波动，且总和恒等于 max_connections。
3、在控制器中插入日志：
\Hyperf\Logger\LoggerFactory::get('db')->info('Conn acquired', ['conn_id' => spl_object_id($connection)]);
多次刷新接口，若输出的 conn_id 重复出现，即表明连接被复用，池化生效。
