Hyperf 数据库组件快速上手:连接池、读写分离、事务与原生 SQL 实战指南
Hyperf 数据库组件快速上手:连接池、读写分离、事务与原生 SQL 实战指南
导读
本文围绕 Hyperf 的数据库组件展开,系统讲解 hyperf/database(ORM 与查询构造器内核)与 hyperf/db-connection(连接池桥接层)的安装、配置、读写分离、多库切换、原生 SQL、事务管理以及 SQL 日志输出等核心用法。读完本文,你将能够在 Hyperf 项目中快速配置多数据库与连接池、通过 Db 门面执行原生 SQL、用事务保证数据一致性,并根据业务场景选择 MySQL / PgSQL / SQLite / SQL Server 等驱动。
组件架构与设计定位
hyperf/database衍生自illuminate/database(Laravel 的数据库组件),我们对它进行了一些改造,大部分功能保持了相同。
从仓库源码结构看,Hyperf 的数据访问体系由两个组件协作完成:
- hyperf/database 组件:数据库内核,包含
Connection、查询构造器(Query/Builder)、Schema 构建器、模型基类(Model/)、迁移(Migrations/)与各类连接器(Connectors/)。它从设计上允许被其它 PHP-FPM 框架或基于 Swoole 的框架直接使用,并不强依赖 Hyperf 容器。 - hyperf/db-connection 组件:面向 Hyperf 的连接池桥接层,基于 hyperf/pool 组件 实现了数据库连接池,并对模型做了新的抽象。它以连接池为桥梁,把数据库组件和事件组件接入 Hyperf 的协程容器中。
两者之间的关系可以在 src/db-connection/src/Connection.php 中直观看到:该连接类同时实现 Hyperf\Contract\ConnectionInterface 与 Hyperf\Database\ConnectionInterface,内部通过 ConnectionFactory 创建真正的数据库连接,并处理 reconnect()、close()、release() 等池化生命周期逻辑。
// src/db-connection/src/Connection.php(节选)
public function reconnect(): bool
{
$this->close();
$this->connection = $this->factory->make($this->config);
// 重置事件分发器与 reconnector ...
return true;
}
也就是说:裸的数据库连接由 hyperf/database 提供,而"在协程中安全地取用、归还连接"这件事由 hyperf/db-connection 负责。
安装
Hyperf 框架
在 Hyperf 框架内使用,直接安装带连接池能力的组件:
composer require hyperf/db-connection
安装后即可通过 Hyperf\DbConnection\Db 门面与 Hyperf\DbConnection\Model\Model 模型基类进行开发。
其它框架
如果是在非 Hyperf 框架(如普通 PHP-FPM 项目或其它 Swoole 框架)中使用,只需引入数据库内核:
composer require hyperf/database
配置
数据库支持多库配置,默认连接名为 default。配置文件约定位于 config/autoload/databases.php,默认配置项如下:
| 配置项 | 类型 | 默认值 | 备注 |
|---|---|---|---|
| driver | string | 无 | 数据库引擎 |
| host | string | 无 | 数据库地址 |
| database | string | 无 | 数据库默认 DB |
| 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 | 心跳 |
| 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),
]
],
];
仓库中 hyperf/db 组件发布的默认配置 在 charset / collation 上默认采用 utf8mb4 与 utf8mb4_unicode_ci,并额外带有 fetch_mode => PDO::FETCH_ASSOC 与 defer_release => false 两个开关,供你按项目实际情况对齐。pool 配置项会被 src/db-connection/src/Pool/DbPool.php 读取,用于构造连接池实例:
$options = Arr::get($this->config, 'pool', []);
$this->frequency = make(Frequency::class, [$this]);
parent::__construct($container, $options);
自定义 PDO 行为(options)
有时候需要修改 PDO 的默认配置,例如希望所有查询字段都返回为 string 类型,此时需要把 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 或云厂商提供的 DB(如从库/分析型实例等)不支持 MySQL prepare 协议,
// 需要将此项设置为 true
PDO::ATTR_EMULATE_PREPARES => false,
],
],
];
这些 options 会被 ConnectionFactory 直接透传给 PDO 构造,因此所有 PDO 常量级的行为(大小写转换、异常模式、NULL 处理、预处理模拟等)都可以在这里统一控制。
读写分离
有时候你希望 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),
],
],
];
注意以上配置中增加了三个键:read、write 和 sticky。read 和 write 的键都包含一个键为 host 的数组,而 read 和 write 的其它配置项继承自外层(如 database、username、password、prefix、charset 等)。因此:
192.168.1.1将作为「读」连接主机;196.168.1.2将作为「写」连接主机;- 两个连接共享外层数组的数据库凭据(用户名/密码)、前缀、字符编码等配置。
如果你想重写主数组中的某些配置,只需要在 read 和 write 数组中覆盖对应键即可。
sticky 是一个可选值,用于立即读取在当前请求周期内已写入数据库的记录。若 sticky 选项被启用,并且当前请求周期内执行过「写」操作,那么任何「读」操作都将使用「写」连接,从而确保同一请求周期内写入的数据可以被立即读取到,避免主从延迟导致的数据不一致问题。是否启用它,取决于应用程序的实际需求。
从源码层面看,这一行为由 src/database/src/Connection.php 的 select() 与 getPdoForSelect() 共同实现:select 默认走 getReadPdo()(读连接),而 insert / update / delete / statement 一律走 getPdo()(写连接);当 sticky 开启且本请求周期内发生过写操作时,getReadPdo() 内部会直接返回写连接的 PDO。仓库测试 src/db-connection/tests/ConnectionTest.php 与 src/db-connection/tests/Stubs/ContainerStub.php 对 read / write / sticky 这套配置组合进行了完整的读写分离验证。
多库配置
多库配置就是在 databases 数组下增加多个连接键,例如同时配置 default 与 test:
<?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),
],
],
];
使用时,只需指定 connection 为 test,即可使用 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;');
Db::connection() 的解析链路在 src/db-connection/src/ConnectionResolver.php:先按连接名从 PoolFactory 拿到对应连接池,再从协程上下文(Context)中复用同协程内已建立的连接,协程退出时通过 defer() 自动归还连接池。默认连接名存放在 $default = 'default' 属性中,可用 setDefaultConnection() 动态修改。
在模型中,只需修改 $connection 字段即可使用对应配置,例如下面的 User 模型使用 test 配置:
<?php
declare(strict_types=1);
namespace App\Model;
/**
* @property int $id
* @property string $mobile
* @property string $realname
*/
class User extends Model
{
/**
* The table associated with the model.
*
* @var string
*/
protected $table = 'user';
/**
* The connection name for the model.
*
* @var string
*/
protected $connection = 'test';
/**
* The attributes that are mass assignable.
*
* @var array
*/
protected $fillable = ['id', 'mobile', 'realname'];
/**
* The attributes that should be cast to native types.
*
* @var array
*/
protected $casts = ['id' => 'integer'];
}
Hyperf 的模型基类 src/db-connection/src/Model/Model.php 继承自 Hyperf\Database\Model\Model,并混入了 HasContainer(从容器解析连接)与 HasRepository(仓库访问)两个特性,因此模型天然感知连接池与容器。
执行原生 SQL 语句
配置好数据库后,便可以使用 Hyperf\DbConnection\Db 进行查询。Db 本身是一个静态代理门面:在 src/db-connection/src/Db.php 中,所有静态调用(select、insert、transaction 等)都会通过 ApplicationContext::getContainer()->get(Db::class) 拿到实例,再转发到默认连接上执行。
Query 查询类
这里主要包括 Select、属性为 READS SQL DATA 的存储过程、函数等查询语句。
select 方法将始终返回一个数组,数组中的每个结果都是一个 StdClass 对象:
<?php
use Hyperf\DbConnection\Db;
$users = Db::select('SELECT * FROM `user` WHERE gender = ?',[1]); // 返回 array
foreach($users as $user){
echo $user->name;
}
Execute 执行类
这里主要包括 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
从 src/database/src/Connection.php 的实现可以看到各方法的返回值契约:insert / statement 返回 bool,update / delete 通过 affectingStatement() 返回受影响行数 int。所有查询都使用 PDO 预处理与绑定参数,避免 SQL 注入风险;select 还会携带第三个参数 $useReadPdo(默认 true),以便配合前面的读写分离机制在必要时强制走写连接(对应 selectFromWriteConnection())。
自动管理数据库事务
你可以使用 Db 的 transaction 方法在数据库事务中执行一组操作。如果事务闭包 Closure 中出现异常,事务将回滚;如果闭包执行成功,事务将自动提交。一旦使用 transaction,就无需再担心手动回滚或提交的问题:
<?php
use Hyperf\DbConnection\Db;
Db::transaction(function () {
Db::table('user')->update(['votes' => 1]);
Db::table('posts')->delete();
});
从 src/database/src/Concerns/ManagesTransactions.php 的源码看,transaction(Closure $callback, int $attempts = 1) 还内置了死锁自动重试能力:当抛出由死锁导致的异常且未超过 $attempts 次数时,会自动回滚后重试;达到最大次数后才把异常抛出。对于高并发写场景,可以显式传入更大的尝试次数,例如 Db::transaction($callback, 3)。
手动管理数据库事务
如果你想要手动开始一个事务,并且对回滚和提交能够完全控制,那么可以使用 Db 的 beginTransaction、commit、rollBack:
use Hyperf\DbConnection\Db;
Db::beginTransaction();
try{
// Do something...
Db::commit();
} catch(\Throwable $ex){
Db::rollBack();
}
需要注意嵌套事务的处理:beginTransaction() 在已处于事务中时会创建保存点(savepoint),commit() 只在外层事务(transactions == 1)时才真正提交,因此多层 transaction() 嵌套是安全的(见 ManagesTransactions.php)。另外,连接池在 src/db-connection/src/Connection.php 的 release() 中做了兜底:如果连接归还连接池时仍处于事务状态(transactionLevel() > 0),会自动回滚并记录错误日志,防止"忘记提交/回滚"的脏事务污染连接池。
输出刚刚执行的 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() 的本质是把连接的 loggingQueries 标志置为 true(见 src/database/src/Connection.php),此后每次 run() 执行都会把 SQL、绑定参数与耗时写入 queryLog 数组。同文件还提供了配套方法:
getQueryLog():返回完整日志数组;getRawQueryLog():返回将绑定参数代入 SQL 后的「原始 SQL」日志(便于直接复制到数据库客户端执行);flushQueryLog():清空日志;disableQueryLog():关闭日志记录。
驱动列表
与 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'),
]
];
仓库中 database-pgsql 组件 提供了对应的连接器与语法类实现。
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'),
// :memory: 为内存数据库,也可以指定文件绝对路径
'database' => env('DB_DATABASE', ':memory:'),
// other sqlite config
]
];
对应实现见 database-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,
]
];
SQL Server 通过 ODBC 数据源名称(odbc_datasource_name)建立连接,需要根据实际环境调整其中的服务器地址、端口与证书参数。
小结
至此,你已经掌握了 Hyperf 数据库组件从安装、连接池配置、读写分离、多库切换到原生 SQL 与事务管理的完整链路:Db 门面负责静态代理转发,ConnectionResolver + PoolFactory 负责协程安全的连接池取用与归还,Connection 负责真正执行 SQL 并区分读写连接,ManagesTransactions 提供带死锁重试的自动事务。进一步深入学习,可以继续阅读仓库中的 模型文档、查询构造器文档、迁移文档 以及 数据库事件文档。