hyperf多库配置核心是定义多个独立连接名并在运行时切换，需在databases.php中为不同引擎或版本配置语义化连接名、完整pool参数及认证选项，通过db::connection()或模型$connection属性调用，不支持跨库join。
Hyperf 多库配置的核心是定义多个独立连接名，并在运行时按需切换，不是改配置重启或动态覆盖 default。关键在于配置清晰、命名语义化、连接池适配到位。
一、在 databases.php 中定义多个连接
编辑 config/autoload/databases.php，在 'connections' 数组下添加多个带唯一 name 的配置项：
- 每个连接必须显式声明
driver、host、port、database、username、password - 推荐使用有业务含义的连接名，如
'log_db'、'report_pg'、'mysql_v80_rds'，避免'db1'这类无意义命名 - 不同数据库引擎（MySQL/PostgreSQL）或大版本（5.7 vs 8.0）必须分设连接，不可混用同一连接池
- charset、collation、timezone 等建议按实际库设置，尤其跨库时字符集不一致易导致乱码
二、为每个连接单独配置连接池参数
每个连接下需完整声明 'pool' 子数组，不能复用默认值：
-
'min_connections'和'max_connections'要按目标数据库实例的实际承载力设置（例如 MySQL 5.7 实例 max_connections=200，其 pool.max_connections 建议 ≤150） - Swow 环境下必须删除旧 style 的 pool 配置，改用 Swow 专用结构：
'check_interval' => 3000（单位毫秒）、'retry_interval' => 100 - 若涉及认证差异（如 MySQL 8.0 的 caching_sha2_password），需在
'options'中补全：PDO::MYSQL_ATTR_SSL_MODE => PDO::SSL_NONE或PDO::ATTR_EMULATE_PREPARES => false
三、运行时切换连接操作数据
不修改配置文件，直接在代码中指定连接名：
- Query Builder：用
Db::connection('log_db')->table('logs')->where(...)->get() - Eloquent 模型：在模型类中设置
protected $connection = 'report_pg'; - 事务：用
Db::connection('mysql_v80_rds')->transaction(function () { ... }); - 注意：Hyperf 不支持跨库 JOIN，关联查询需拆成多次查询 + 应用层组装
四、验证与调试建议
配置完成后快速确认是否生效：
- 启动服务前执行
rm -rf runtime/container，防止旧连接池缓存残留 - 在控制器中打印
Db::connection('log_db')->getPdo()查看当前连接的 host/database 是否匹配预期 - 开启 SQL 日志（
'enable_logging' => true）观察实际执行的连接名和 SQL - 压测时关注连接数是否超出目标库的
max_connections，及时调整 pool.max_connections
