Hyperf 数据库快速上手:连接池、读写分离、多库配置与原生 SQL 执行全指南
Hyperf 数据库快速上手:连接池、读写分离、多库配置与原生 SQL 执行全指南
导读
本文以 Hyperf 官方文档「数据库快速开始」(docs/id/db/quick-start.md)为骨架,系统讲解在 Hyperf 中接入关系型数据库的完整链路:从安装 hyperf/db-connection、编写 config/autoload/databases.php 配置,到使用 Db 门面执行原生 SQL、开启读写分离与多库连接、管理事务,再到 PgSQL/SQLite/SQL Server 等扩展驱动。读完本文,你将能够独立完成 Hyperf 项目的数据库初始化、连接池调优、主从库切换与事务落地,并理解底层连接池与协程上下文的工作机制。
组件关系:hyperf/database 与 hyperf/db-connection
hyperf/database 组件源自 Laravel 的 illuminate/database,Hyperf 团队对其进行了改造,使其能够运行在普通 PHP-FPM 框架以及基于 Swoole 的协程框架中,大部分 API 与使用习惯保持不变。
而在 Hyperf 中实际使用数据库时,还必须引入 hyperf/db-connection。该组件承担「桥梁」角色:
- 基于 hyperf/pool 实现数据库连接池;
- 为模型提供新的抽象基类;
- 将数据库组件与事件组件(Event)打通,让 Hyperf 能够监听查询执行、事务提交等生命周期事件。
这一点在源码中可以得到印证:hyperf/db-connection 的 ConnectionResolver.php 从连接池工厂获取连接,并借助 Hyperf\Context\Context 将连接对象绑定到当前协程上下文,协程结束(或通过 defer 延迟回调)时自动把连接归还连接池。这正是 Hyperf 数据库连接能够在协程间隔离、复用的核心机制。
安装
在 Hyperf 框架中安装
composer require hyperf/db-connection
在其他框架中使用
如果项目不是 Hyperf,而是其他 PHP-FPM 或 Swoole 框架,则只需安装数据库核心组件:
composer require hyperf/database
数据库配置
默认配置与参数说明
配置位于 config/autoload/databases.php,支持多数据库,其中 default 作为主连接。核心参数如下:
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| driver | string | 无 | 数据库引擎 |
| host | string | 无 | 数据库地址 |
| database | string | 无 | 默认数据库 |
| username | string | 无 | 数据库用户名 |
| password | string | null | 数据库密码 |
| charset | string | utf8 | 数据库字符集 |
| collation | string | utf8_unicode_ci | 数据库排序规则 |
| prefix | string | '' | 表前缀 |
| timezone | string | null | 数据库时区 |
| pool.min_connections | int | 1 | 连接池最小连接数 |
| pool.max_connections | int | 10 | 连接池最大连接数 |
| pool.connect_timeout | float | 10.0 | 建立连接超时时间 |
| pool.wait_timeout | float | 3.0 | 获取连接等待超时时间 |
| pool.heartbeat | int | -1 | 心跳检测(-1 表示不启用) |
| pool.max_idle_time | float | 60.0 | 连接最大空闲时间 |
| options | array | — | PDO 选项 |
一份完整的默认配置示例:
<?php
return [
'default' => [
'driver' => env('DB_DRIVER', 'mysql'),
'host' => env('DB_HOST', 'localhost'),
'port' => env('DB_PORT', 3306),
'database' => env('DB_DATABASE', 'hyperf'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => env('DB_CHARSET', 'utf8'),
'collation' => env('DB_COLLATION', 'utf8_unicode_ci'),
'prefix' => env('DB_PREFIX', ''),
'pool' => [
'min_connections' => 1,
'max_connections' => 10,
'connect_timeout' => 10.0,
'wait_timeout' => 3.0,
'heartbeat' => -1,
'max_idle_time' => (float) env('DB_MAX_IDLE_TIME', 60),
]
],
];
从源码角度看,连接池的参数解析发生在 DbPool.php:它从配置中心读取 databases.{name} 段,并把其中的 pool 数组直接传给 Hyperf\Pool\Pool 基类。因此 min_connections、max_connections、connect_timeout、wait_timeout、heartbeat、max_idle_time 均作用于连接池的伸缩、排队与保活行为——在高并发协程场景下,max_connections 决定了可同时活跃的数据库连接上限,而 wait_timeout 控制连接耗尽时调用方的等待时长。
自定义 PDO 选项
有时需要调整 PDO 的默认行为,例如希望所有字段统一以字符串返回,将 PDO 选项 ATTR_STRINGIFY_FETCHES 设为 true 即可:
<?php
return [
'default' => [
'driver' => env('DB_DRIVER', 'mysql'),
'host' => env('DB_HOST', 'localhost'),
'port' => env('DB_PORT', 3306),
'database' => env('DB_DATABASE', 'hyperf'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => env('DB_CHARSET', 'utf8'),
'collation' => env('DB_COLLATION', 'utf8_unicode_ci'),
'prefix' => env('DB_PREFIX', ''),
'pool' => [
'min_connections' => 1,
'max_connections' => 10,
'connect_timeout' => 10.0,
'wait_timeout' => 3.0,
'heartbeat' => -1,
'max_idle_time' => (float) env('DB_MAX_IDLE_TIME', 60),
],
'options' => [
// 框架默认配置
PDO::ATTR_CASE => PDO::CASE_NATURAL,
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_ORACLE_NULLS => PDO::NULL_NATURAL,
PDO::ATTR_STRINGIFY_FETCHES => false,
// 若使用非原生 MySQL 或某些云厂商数据库(如只读实例、分析型实例)不支持 MySQL prepare 协议,请将其设为 true
PDO::ATTR_EMULATE_PREPARES => false,
],
],
];
配置中的 options 数组会经由 ConnectionFactory.php 的 PDO 解析闭包最终传入 PDO 构造器。需要注意的是:默认 PDO::ERRMODE_EXCEPTION 意味着 SQL 执行出错会直接抛出异常,业务代码应据此做好异常捕获;ATTR_EMULATE_PREPARES 在云数据库等不支持原生预处理协议的场景下必须调整为 true。
读写分离(Read/Write Splitting)
当 SELECT 希望走一个连接、INSERT/UPDATE/DELETE 走另一个连接时,Hyperf 的原生查询、查询构建器与模型均可直接支持。配置方式如下:
<?php
return [
'default' => [
'driver' => env('DB_DRIVER', 'mysql'),
'read' => [
'host' => ['192.168.1.1'],
],
'write' => [
'host' => ['196.168.1.2'],
],
'sticky' => true,
'database' => env('DB_DATABASE', 'hyperf'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => env('DB_CHARSET', 'utf8'),
'collation' => env('DB_COLLATION', 'utf8_unicode_ci'),
'prefix' => env('DB_PREFIX', ''),
'pool' => [
'min_connections' => 1,
'max_connections' => 10,
'connect_timeout' => 10.0,
'wait_timeout' => 3.0,
'heartbeat' => -1,
'max_idle_time' => (float) env('DB_MAX_IDLE_TIME', 60),
],
],
];
注意上述示例在配置数组中新增了三个 key:read、write 和 sticky。read 与 write 内部都是一个包含 host 的数组;除 host 外,其余数据库配置(用户名、密码、表前缀、字符集等)均从主配置数组共享。如果需要覆盖主数组中的某些配置,直接在 read/write 数组中重写即可。上面的例子中,192.168.1.1 将作为读连接 host,196.168.1.2 作为写连接 host,两者共享 mysql 主配置里的凭据与编码等。
sticky 是可选的布尔值,用于决定是否在同一个请求周期内立即读取刚写入的数据:启用 sticky 后,若当前请求周期内已发生写操作,后续读操作将复用写连接,从而避免因主从复制延迟导致「写后读不到」的数据不一致问题。是否启用取决于业务对一致性的要求。
在底层,ConnectionFactory.php 的 make() 会检测配置中是否存在 read 段,存在时调用 createReadWriteConnection():先基于写配置创建主连接,再通过 setReadPdo() 注入一个读 PDO 解析闭包。读连接只会在执行读语句时惰性建立,且当 read.host 以数组形式给出多个地址时,会通过 Arr::random 随机选取并在连接失败时自动轮换下一个 host。
多数据库配置(Multiple Databases)
多数据库配置示例如下:
<?php
return [
'default' => [
'driver' => env('DB_DRIVER', 'mysql'),
'host' => env('DB_HOST', 'localhost'),
'database' => env('DB_DATABASE', 'hyperf'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => env('DB_CHARSET', 'utf8'),
'collation' => env('DB_COLLATION', 'utf8_unicode_ci'),
'prefix' => env('DB_PREFIX', ''),
'pool' => [
'min_connections' => 1,
'max_connections' => 10,
'connect_timeout' => 10.0,
'wait_timeout' => 3.0,
'heartbeat' => -1,
'max_idle_time' => (float) env('DB_MAX_IDLE_TIME', 60),
],
],
'test'=>[
'driver' => env('DB_DRIVER', 'mysql'),
'host' => env('DB_HOST2', 'localhost'),
'database' => env('DB_DATABASE', 'hyperf'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => env('DB_CHARSET', 'utf8'),
'collation' => env('DB_COLLATION', 'utf8_unicode_ci'),
'prefix' => env('DB_PREFIX', ''),
'pool' => [
'min_connections' => 1,
'max_connections' => 10,
'connect_timeout' => 10.0,
'wait_timeout' => 3.0,
'heartbeat' => -1,
'max_idle_time' => (float) env('DB_MAX_IDLE_TIME', 60),
],
],
];
使用时,将连接名指定为 test 即可命中对应配置:
<?php
use Hyperf\DbConnection\Db;
// default
Db::select('SELECT * FROM user;');
Db::connection('default')->select('SELECT * FROM user;');
// test
Db::connection('test')->select('SELECT * FROM user;');
在模型中,通过重写 connection 属性指定连接。下面的 User 模型使用了 test 配置:
<?php
declare(strict_types=1);
namespace App\Model;
/**
* @property int $id
* @property string $mobile
* @property string $realname
*/
class User extends Model
{
/**
* 模型关联的表。
*
* @var string
*/
protected $table = 'user';
/**
* 模型使用的连接名。
*
* @var string
*/
protected $connection = 'test';
/**
* 允许批量赋值的属性。
*
* @var array
*/
protected $fillable = ['id', 'mobile', 'realname'];
/**
* 需要转为原生类型的属性。
*
* @var array
*/
protected $casts = ['id' => 'integer'];
}
补充说明:Hyperf 中的模型基类位于 src/db-connection/src/Model/Model.php,它在 Hyperf\Database\Model\Model 基础上混入了容器访问与仓储(Repository)相关 trait,实际使用中你只需继承 Hyperf\DbConnection\Model\Model(或项目骨架生成的 App\Model\Model)。模型内指定的 $connection 最终通过查询构建器透传到对应名称的连接池。
执行原生 SQL
完成数据库配置后,即可通过 Hyperf\DbConnection\Db 执行查询。Db.php 是一个静态门面:__callStatic 会先从容器取出 Db 实例,再转发到默认连接上同名方法;connection($name) 则通过 ConnectionResolver 返回指定连接。
查询类(Query Class)
主要覆盖 SELECT、带有 READS SQL DATA 属性的存储过程、函数以及其他查询类语句。select 方法始终返回数组,数组中的每个结果是 StdClass 对象:
<?php
use Hyperf\DbConnection\Db;
$users = Db::select('SELECT * FROM `user` WHERE gender = ?', [1]); // 返回数组
foreach ($users as $user) {
echo $user->name;
}
执行类(Execute Class)
主要覆盖 INSERT、UPDATE、DELETE、带有 MODIFIES SQL DATA 属性的存储过程及其他执行类语句:
<?php
use Hyperf\DbConnection\Db;
$inserted = Db::insert('INSERT INTO user (id, name) VALUES (?, ?)', [1, 'Hyperf']); // 返回 bool,表示是否成功
$affected = Db::update('UPDATE user set name = ? WHERE id = ?', ['John', 1]); // 返回受影响行数(int)
$affected = Db::delete('DELETE FROM user WHERE id = ?', [1]); // 返回受影响行数(int)
$result = Db::statement("CALL pro_test(?, '?')", [1, 'your words']); // 返回 bool。CALL pro_test(?, ?) 为带 MODIFIES SQL DATA 属性的存储过程
与 select 不同,insert/statement 返回布尔值,update/delete 返回受影响行数——这与 Db.php 中标注的 @method 返回类型完全一致,可在 IDE 中直接获得类型提示。
事务自动管理
使用 Db 的 transaction 方法,在 Closure 内执行操作:一旦闭包内抛出异常,事务自动回滚;全部成功则自动提交,无需手动处理:
<?php
use Hyperf\DbConnection\Db;
Db::transaction(function () {
Db::table('user')->update(['votes' => 1]);
Db::table('posts')->delete();
});
底层实现在 ManagesTransactions.php:transaction() 先 beginTransaction(),回调成功则 commit(),捕获异常则回滚;若异常由死锁(deadlock)引起且还有剩余尝试次数,还会自动重试(transaction 的第二个参数 $attempts 控制最大尝试次数,默认 1)。MySQL 在死锁时会回滚整个事务,因此重试仅当嵌套事务(transactions > 1)时才会被阻止并直接抛出。
事务手动管理
需要完全掌控事务时,可用 Db 的 beginTransaction、commit、rollBack 手动管理:
<?php
use Hyperf\DbConnection\Db;
Db::beginTransaction();
try {
// 执行你的操作...
Db::commit();
} catch (\Throwable $ex) {
Db::rollBack();
}
需要特别提醒:在连接池场景下,连接归还时会检查事务层级。从 Connection.php 的 release() 逻辑可以看到,若连接归还时仍处于事务中(transactionLevel() > 0),组件会自动回滚并输出错误日志「Maybe you've forgotten to commit or rollback the MySQL transaction.」——因此务必在协程结束前提交或回滚事务,避免把未提交的事务随连接一起归还连接池。
打印刚执行的 SQL
此方法仅限开发环境使用。部署到生产环境前必须移除,否则会造成内存泄漏与数据错乱。
如需在生产环境记录 SQL,请使用事件监听方案,参见 数据库事件。
<?php
use Hyperf\DbConnection\Db;
use Hyperf\Collection\Arr;
use App\Model\Book;
// 开启 SQL 查询日志
Db::enableQueryLog();
$book = Book::query()->find(1);
// 打印最后一条 SQL 数据
var_dump(Arr::last(Db::getQueryLog()));
从源码看,enableQueryLog()、getQueryLog() 定义于 src/database/src/Connection.php:开启后,每次查询执行都会把 SQL、绑定参数与耗时追加到内存日志数组,且不设上限,这正是官方文档提示生产环境禁用(防止内存泄漏)的原因。
支持的驱动列表
与 illuminate/database 不同,hyperf/database 默认仅提供 MySQL 驱动。目前还提供了 PgSQL、SQLite、SQL Server 等扩展驱动。若默认 MySQL 驱动不满足需求,可自行安装对应驱动。
PgSQL 驱动
安装
要求 Swoole >= 5.1.0,且编译时开启 --enable-swoole-pgsql 选项。
composer require hyperf/database-pgsql
配置文件
// config/autoload/databases.php
return [
// 其他配置
'pgsql'=>[
'driver' => env('DB_DRIVER', 'pgsql'),
'host' => env('DB_HOST', 'localhost'),
'database' => env('DB_DATABASE', 'hyperf'),
'port' => env('DB_PORT', 5432),
'username' => env('DB_USERNAME', 'postgres'),
'password' => env('DB_PASSWORD'),
'charset' => env('DB_CHARSET', 'utf8'),
]
];
SQLite 驱动
安装
要求 Swoole >= 5.1.0,且编译时开启 --enable-swoole-sqlite 选项。
composer require hyperf/database-sqlite
配置文件
// config/autoload/databases.php
return [
// 其他配置
'sqlite'=>[
'driver' => env('DB_DRIVER', 'sqlite'),
'host' => env('DB_HOST', 'localhost'),
'database' => env('DB_DATABASE', ':memory:'),
// :memory: 表示内存数据库,也可以填写绝对文件路径
// 其他 sqlite 配置
]
];
SQL Server 驱动
安装
该驱动仍处于孵化阶段,目前无法保证所有功能正常工作,欢迎提交反馈。
要求 Swoole >= 5.1.0,依赖 pdo_odbc,编译时需要开启 --with-swoole-odbc。
composer require hyperf/database-sqlserver-incubator
配置文件
// config/autoload/databases.php
return [
// 其他配置
'sqlserver' => [
'driver' => env('DB_DRIVER', 'sqlsrv'),
'host' => env('DB_HOST', 'mssql'),
'database' => env('DB_DATABASE', 'hyperf'),
'port' => env('DB_PORT', 1443),
'username' => env('DB_USERNAME', 'SA'),
'password' => env('DB_PASSWORD'),
'odbc_datasource_name' => 'DRIVER={ODBC Driver 18 for SQL Server};SERVER=127.0.0.1,1433;TrustServerCertificate=yes;database=hyperf',
'odbc' => true,
]
];
从源码理解连接池与协程的协作
最后,把配置与源码串起来看,Hyperf 数据库连接的整体工作流程如下:
- 应用启动后,
DbPool依据config/autoload/databases.php中databases.{连接名}段初始化连接池(DbPool.php),并将pool配置交给通用连接池基类管理; - 协程中调用
Db::select()等静态方法时,Db门面经ConnectionResolver解析:先从协程上下文(Context)中取当前协程已持有的连接,没有则向连接池get()借出连接并绑定到上下文(ConnectionResolver.php); - 协程结束(或通过
defer延迟注册)时,连接归还连接池;归还前若发现事务未结束会自动回滚,错误计数超过 100 的连接会在下次取用时强制重建(Connection.php); - 断线重连由
Connection的reconnect()与refresh()完成:重建 PDO 后会重新绑定事件分发器与重连回调,保证长连接失效时能平滑恢复。
理解这一链路后,你就能针对高并发场景合理配置 pool.max_connections、wait_timeout 与 heartbeat,并在读写分离、多库切换之间游刃有余。继续深入可以阅读仓库中的 数据库模型、查询构建器、迁移 与 数据库事件 等文档。