Hyperf 数据库快速上手:hyperf/database 连接池、读写分离与原生 SQL 实战全解
Hyperf 数据库快速上手:hyperf/database 连接池、读写分离与原生 SQL 实战全解
本篇指南聚焦 Hyperf 框架的数据库接入方案,围绕 hyperf/database 与 hyperf/db-connection 两大组件,完整讲解安装、多库/读写分离配置、原生 SQL 执行、事务管理以及 SQL 日志输出。读者学完后,可以在 Hyperf 项目中独立配置数据库连接池,并通过 Db 门面或模型完成日常增删改查与事务控制,同时理解底层连接池与协程上下文的协作原理。
组件架构:hyperf/database 与 hyperf/db-connection 的分工
hyperf/database 组件衍生自 illuminate/database(Laravel 的 ORM 组件),Hyperf 对其进行了改造,绝大部分功能保持一致,设计上允许用于其它 PHP-FPM 框架或基于 Swoole 的框架中。如果你已经在 Laravel 中熟悉了查询构造器、Eloquent 模型等用法,在 Hyperf 中可以几乎无缝迁移。
而在 Hyperf 中,真正把数据库组件接入协程体系的关键是 hyperf/db-connection 组件:它基于 hyperf/pool 实现了数据库连接池,并对模型做了新的抽象。以此作为桥梁,Hyperf 才能把数据库组件及事件组件(如 QueryExecuted 事件)统一接入进来。其依赖关系可以从 db-connection/composer.json 中看到:hyperf/db-connection 依赖 hyperf/database、hyperf/pool、hyperf/context、hyperf/coroutine 等组件,要求 PHP >= 8.2。
安装
Hyperf 框架
composer require hyperf/db-connection
其它框架(仅需数据库组件本身)
composer require hyperf/database
安装完成后,在 Hyperf 项目中执行 php bin/hyperf.php 相关命令或直接使用即可;组件会通过 ConfigProvider 自动注册连接解析器与连接池工厂(见 ConfigProvider.php)。
配置详解
默认配置如下,数据库支持多库配置,默认连接名为 default:
| 配置项 | 类型 | 默认值 | 备注 |
|---|---|---|---|
| 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 配置 |
其中 pool 系列参数在底层由 hyperf/pool 的 Pool.php 解析:min_connections / max_connections 决定连接池的容量(协程 Channel 的容量即为 max_connections),connect_timeout 是建立新连接的等待超时,wait_timeout 是连接池资源耗尽后等待归还的超时,超过该时间会抛出 Connection pool exhausted 异常,heartbeat 为 -1 表示不需要心跳检测,max_idle_time 是连接最大闲置时间。DbPool 通过 databases.{连接名} 读取配置,并在解析时自动写入 name 字段以保证模型查询构造器拿到正确的连接(见 DbPool.php)。
在 Hyperf 项目中,配置文件通常位于 config/autoload/databases.php,完整默认示例(发布自 publish/databases.php):
<?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),
]
],
];
实际发布的配置文件还包含 cache(模型缓存)与 commands(gen:model 模型生成命令的默认路径、强制 casts 等)两个可选分组,可按需使用。
自定义 PDO 选项
有时候你需要修改 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,
],
],
];
读写分离
有时候你希望 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 数组即可。因此在这个例子中:192.168.1.1 将作为「读」连接主机,而 196.168.1.2 将作为「写」连接主机。这两个连接会共享主配置数组的各项设置,如数据库凭据(用户名 / 密码)、前缀、字符编码等。
sticky 是一个可选值,它可用于立即读取在当前请求周期内已写入数据库的记录。若 sticky 选项被启用,并且当前请求周期内执行过「写」操作,那么任何「读」操作都将使用「写」连接,这样可确保同一个请求周期内写入的数据可以被立即读取到,从而避免主从延迟导致数据不一致的问题。是否启用它,取决于应用程序的需求。
底层原理
从源码看,当配置中存在 read 键时,ConnectionFactory::make() 会走 createReadWriteConnection 分支:以 write 配置建立写连接,并通过 setReadPdo() 挂载由 read 配置解析出的读连接(见 ConnectionFactory.php)。read / write 中的 host 支持数组,连接时会通过 Arr::shuffle 随机打乱主机顺序逐个尝试,直到某个主机连接成功(见 ConnectionFactory.php),可用于简单的多从库负载。
而 sticky 的实现位于 database/src/Connection.php 的 getReadPdo():当 transactions > 0(事务中)或 recordsModified 为真且配置了 sticky 时,读取操作直接返回写连接的 PDO。recordsModified 会在执行 insert/update/delete 等写操作后被置为 true(通过 recordsHaveBeenModified),连接归还连接池时会通过 resetRecordsModified() 复位(见 db-connection/src/Connection.php 的 release()),从而保证 sticky 语义只在单个请求周期内生效。
多库配置
多库配置只需在配置数组中增加更多连接名即可:
<?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;');
模型中修改 connection 字段,即可使用对应配置,例如下面这个 Model 使用 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'];
}
从源码看,模型通过 getConnectionName() 返回 $connection 配置,并在 newQuery() 时经由 database/src/Model/Model.php 的 resolveConnection 解析到对应的连接池;模型基类 Hyperf\DbConnection\Model\Model(见 db-connection/src/Model/Model.php)则额外注入了容器访问与仓储(Repository)能力。
执行原生 SQL 语句
配置好数据库后,便可以使用 Hyperf\DbConnection\Db 进行查询。Db 是一个门面(Facade)类,其 __callStatic 会从容器中取出 Db 实例,再通过 ConnectionResolver 解析默认连接并把方法调用转发到底层连接对象上(见 Db.php),因此你可以像调用实例方法一样静态调用所有数据库方法。
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;
}
查询语句使用 ? 占位符并通过第二个参数传入绑定值,底层由 PDO 预处理执行,可有效避免 SQL 注入。类似的查询方法还有 selectOne(返回单行)、cursor(返回生成器逐行迭代)等,这些方法签名均可在 Db.php 的 @method 注解 中看到。
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
注意返回值差异:insert 与 statement 返回布尔值表示是否成功,update 与 delete 返回受影响的行数(int)。底层实现中,update / delete 经由 affectingStatement 执行并通过 statement->rowCount() 统计受影响行数(见 database/src/Connection.php)。
自动管理数据库事务
你可以使用 Db 的 transaction 方法在数据库事务中运行一组操作。如果事务的闭包 Closure 中出现一个异常,事务将会回滚;如果事务闭包执行成功,事务将自动提交。一旦使用了 transaction,就不再需要担心手动回滚或提交的问题:
<?php
use Hyperf\DbConnection\Db;
Db::transaction(function () {
Db::table('user')->update(['votes' => 1]);
Db::table('posts')->delete();
});
transaction 方法的实现位于 ManagesTransactions.php:它在一个 for 循环中反复执行「开启事务 → 执行闭包 → 成功则 commit、异常则回滚并重试」,第二个参数 attempts 默认值为 1,可用于配置死锁等场景下的自动重试次数。
手动管理数据库事务
如果你想要手动开始一个事务,并且对回滚和提交能够完全控制,那么可以使用 Db 的 beginTransaction、commit、rollBack:
use Hyperf\DbConnection\Db;
Db::beginTransaction();
try{
// Do something...
Db::commit();
} catch(\Throwable $ex){
Db::rollBack();
}
底层通过 ManagesTransactions trait 维护了一个 transactions 计数器以支持嵌套事务(savepoint)语义:只有最外层事务(transactions == 1)才真正执行 PDO 的 commit() / rollBack(),内层事务仅调整计数(见 ManagesTransactions.php)。
需要特别提醒:Hyperf 的连接是协程池化的。连接在归还连接池时(db-connection/src/Connection.php 的 release()),如果检测到事务层级 transactionLevel() > 0,会强制 rollBack(0) 并记录一条错误日志「Maybe you've forgotten to commit or rollback the MySQL transaction.」,以阻止未完成的事务污染后续协程。因此在手动事务中,务必保证 commit / rollBack 在异常路径上也会被执行。
输出刚刚执行的 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,此后每次查询都会以 <a href="https://link.gitcode.com/i/9ee014338aebaaca91124943e3ea0e1d" target="_blank">'query' => ..., 'bindings' => ..., 'time' => ...] 的形式追加到 queryLog 数组(见 [database/src/Connection.php 与 database/src/Connection.php)。由于该机制会把所有 SQL 保存在内存中,长时间运行会引发严重的内存泄露和数据混淆,因此务必只在开发环境开启。
线上记录 SQL,请使用事件监听方案,即监听 Hyperf\Database\Events\QueryExecuted 事件,官方发布的监听器示例 DbQueryExecutedListener.php 会把连接名、执行耗时与绑定参数替换后的完整 SQL 写入名为 sql 的日志通道(debug 级别),相关事件的更多用法可参考 事件监听。
驱动列表
与 illuminate/database 不同,hyperf/database 默认只提供了 MySQL 驱动(createConnector 的默认匹配分支仅包含 mysql,见 ConnectionFactory.php),目前还提供了 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'),
// :memory: 为内存数据库 也可以指定文件绝对路径
'database' => env('DB_DATABASE', ':memory:'),
// other sqlite config
]
];
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,
]
];
驱动配置的核心是 driver 键:ConnectionFactory::createConnector() 会优先从容器中查找 db.connector.{driver} 注册的连接器,各驱动包正是通过这种方式向容器注册自己的 Connector 与 Connection 实现,因此无需修改框架核心代码即可扩展新的数据库引擎。