Hyperf 数据库快速入门:从安装配置到连接池、读写分离与事务实战
Hyperf 数据库快速入门:从安装配置到连接池、读写分离与事务实战
Hyperf 是一个基于 Swoole 的协程框架,其数据库组件由 hyperf/database(源自 illuminate/database 的改写版本)与 hyperf/db-connection(基于 hyperf/pool 实现的数据库连接池桥接层)组成。本文以 docs/en/db/quick-start.md 为主线,结合仓库源码,带你完成数据库组件的安装、多连接配置、读写分离、原生 SQL 执行、事务管理、SQL 日志记录以及 PgSQL / SQLite / SQL Server 驱动接入的完整实战,同时从源码层面理解连接池与协程上下文的工作机制。
组件架构:database 与 db-connection 的分工
hyperf/database 是从 illuminate/database 派生而来的 ORM 与查询构建器组件,绝大部分方法保持与 Laravel 一致(例如 select、insert、update、delete、table、模型 Eloquent 相关能力),并针对 PHP-FPM 与 Swoole 两类运行环境做了适配改造。
而 hyperf/db-connection 则负责将数据库连接以连接池的方式纳入 Hyperf 体系。它以 hyperf/pool 为基础实现连接池(见 DbPool),并作为桥梁把数据库连接、事件(QueryExecuted 等)与 Hyperf 框架整合起来。因此:
- 在 Hyperf 框架内使用数据库:安装
hyperf/db-connection(它内部依赖hyperf/database); - 在其他框架中仅需使用查询构建器/ORM:安装
hyperf/database。
安装
Hyperf 框架内安装
composer require hyperf/db-connection
安装后,hyperf/db-connection 会通过 ConfigProvider 自动注册相关服务,并将默认配置发布到 config/autoload/databases.php(仓库中对应的发布模板见 databases.php)。
其他框架中使用
composer require hyperf/database
数据库配置
默认配置支持同时配置多个数据库连接;当不指定连接名称时,会使用名为 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),
]
],
];
自定义 PDO 配置(options)
有时需要修改默认的 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,
],
],
];
说明:仓库实际发布的 databases.php 模板中还额外包含了
cache(模型缓存相关,默认使用Hyperf\ModelCache\Handler\RedisHandler)与commands(gen:model命令的默认生成路径、继承基类等)配置段,生产环境中可按需保留或精简。
读写分离配置
有时我们希望 SELECT 语句使用一个数据库连接,而 INSERT、UPDATE、DELETE 语句使用另一个数据库连接。在 Hyperf 中,无论使用原生 SQL、查询构建器还是模型,都可以轻松实现读写分离。
配置示例如下:
<?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将作为「读」连接的 host;196.168.1.2将作为「写」连接的 host;- 两个连接共享
default数组中的其余配置,如账号密码(username/password)、表前缀、字符编码等。
sticky 是可选配置,用于在当前请求周期内立即读到刚刚写入数据库的记录。当 sticky 开启且当前请求周期内已发生「写」操作时,随后的「读」操作会复用「写」连接,从而保证同一请求周期内写入的数据立即可读,避免主从延迟造成的数据不一致问题。是否开启该选项取决于应用的实际需求。
从源码结构看,连接对象的
select系方法支持$useReadPdo参数(见 Db.php 的@method定义与 DbConnection trait),读写分离正是通过读写 PDO 的切换来实现的。
多数据库连接配置
多数据库配置示例如下:
<?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:
<?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 属性值,来改变某个模型默认使用的数据库连接:
注意:属性可见性必须设置为
protected
<?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'];
}
从源码看,DbPool 在创建连接池时会读取
databases.{name}配置,并把配置项的name重写为连接名称,以确保模型查询构建器能拿到正确的连接。模型指定连接后,其查询都会通过对应的连接池取连接。
执行原生 SQL 语句
配置好数据库后,就可以使用 Hyperf\DbConnection\Db 进行查询了。Db 是一个静态门面,底层通过 ConnectionResolver 获取当前连接,并把调用委托给实际的数据库连接(见 Db.php 的 __callStatic 实现)。
查询数据(SELECT)
包括 select 查询语句,以及读取 SQL 数据的存储过程和函数。
select 方法始终返回数组,数组中的每个结果都是一个 StdClass 对象:
<?php
use Hyperf\DbConnection\Db;
$users = Db::select('SELECT * FROM `user` WHERE gender = ?',[1]); // 返回数组
foreach($users as $user){
echo $user->name;
}
修改数据(INSERT / UPDATE / DELETE)
包括 Insert、Update、Delete 等执行语句,以及修改 SQL 数据的存储过程:
<?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返回array、insert返回bool、update/delete返回int、statement返回bool)与 Db.php 中@method注释以及 DbConnection trait 的方法签名完全一致,可直接作为编码参考。
事务管理
自动管理数据库事务
使用 Db 的 transaction 方法可以将一组操作作为一个数据库事务运行。如果事务闭包中抛出异常,事务将自动回滚;如果闭包执行成功,事务将自动提交。使用 transaction 方法时无需担心回滚或提交:
<?php
use Hyperf\DbConnection\Db;
Db::transaction(function () {
Db::table('user')->update(['votes' => 1]);
Db::table('posts')->delete();
});
从源码看,事务底层实现在 ManagesTransactions trait 中:transaction(Closure $callback, int $attempts = 1) 会先 beginTransaction(),在 try 中执行闭包并 commit(),捕获 Exception 时按 $attempts 次数重试,捕获 Throwable 时直接 rollBack() 并重新抛出。transaction 的第二个参数 $attempts 即为事务重试次数,默认 1。
手动管理数据库事务
如果你希望手动开启事务并完全控制回滚与提交,可以使用 beginTransaction、commit、rollBack 方法:
use Hyperf\DbConnection\Db;
Db::beginTransaction();
try{
// Do something...
Db::commit();
} catch(\Throwable $ex){
Db::rollBack();
}
注解式事务(源码补充)
除了手动与闭包式事务,hyperf/db-connection 还提供了声明式事务支持:在方法上标注 #<a href="https://link.gitcode.com/i/8d1993144b79afa862f36090b533b47c" target="_blank">Transactional] 注解(见 [Transactional.php),由 TransactionAspect 切面拦截,通过 Db::connection($transactional->connection)->transaction(...) 包裹原方法执行。注解支持指定 connection(默认 default)与 attempts(默认 1)两个参数,适合用于 Service 层方法级事务控制。
连接归还时的自动兜底(源码细节)
从 Connection.php 的 release() 实现可以看出,连接归还连接池时会做安全兜底:如果连接的事务层级(transactionLevel())大于 0,会强制 rollBack(0) 并输出错误日志("Maybe you've forgotten to commit or rollback the MySQL transaction."),防止未提交事务的连接污染连接池;当连接错误计数超过 100 时,会把该连接标记为坏连接,在下一次使用时重建。这一机制保证了协程环境下连接复用的安全性。
记录原生 SQL 查询日志
该方法仅适用于开发环境,上线部署前必须移除,否则在 Swoole CLI 常驻内存环境下会引起严重的内存泄漏和数据一致性问题。
可以通过 数据库事件监听器 来记录 SQL 查询:
<?php
use Hyperf\DbConnection\Db;
use Hyperf\Collection\Arr;
use App\Model\Book;
// 开启 SQL 数据日志记录功能
// WARNING:在 Swoole CLI 环境下会导致内存泄漏与数据一致性问题,仅限本地开发调试使用!
Db::enableQueryLog();
$book = Book::query()->find(1);
// 打印最后一条 SQL 查询
var_dump(Arr::last(Db::getQueryLog()));
更推荐的方式是基于事件监听实现:组件发布了 DbQueryExecutedListener 示例,监听 Hyperf\Database\Events\QueryExecuted 事件,将 SQL 中绑定的参数回填后,以 [连接名][耗时]SQL 的格式通过日志通道输出。实际使用时只需将该类复制到自己的 App\Listener 命名空间并按需调整即可。
支持的数据库驱动列表
与 illuminate/database 不同,hyperf/database 默认仅提供 MySQL 驱动(对应仓库中的 MySqlConnector),同时目前还提供 PgSQL、SQLite 与 SQL Server 等驱动(对应仓库目录 database-pgsql、database-sqlite、database-sqlserver)。如果默认的 mysql 无法满足需求,可自行安装对应驱动。
PgSql 驱动
安装
要求 Swoole >= 5.1.0,且编译时需启用 --enable-swoole-pgsql:
composer require hyperf/database-pgsql
配置文件
// config/autoload/databases.php
return [
// Other configurations
'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 [
// Other configurations
'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 [
// Other configurations
'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,
]
];
连接池与协程上下文:快速上手的底层原理
在 Swoole 协程环境下,数据库连接不能跨协程共享,Hyperf 通过「连接池 + 协程上下文」的组合解决了连接复用与隔离问题:
- 连接池:DbPool 继承自
Hyperf\Pool\Pool,按配置创建最小/最大连接数,Connection(见 Connection.php)封装了连接的建立(reconnect())、复用检查、心跳与坏连接重建(错误计数超过 100 时标记为待重建); - 协程上下文:ConnectionResolver 以
database.connection.{name}为 key 将连接存入协程上下文(Context),同一协程内重复获取直接命中,协程结束时通过defer()自动将连接释放回连接池。这意味着在使用Db::select()、模型查询时,你无需关心连接的借用与归还,框架已自动处理; - 断线刷新:连接建立后,Connection::reconnect() 会重新注入事件分发器(
EventDispatcherInterface)与reconnector回调;当 MySQL 服务端主动断开连接时,会触发refresh()使用相同配置重建 PDO 并替换当前连接的pdo/readPdo,从源码结构看这是连接保持可用性的关键保障。
理解这一机制,你就能明白为什么读写分离、多连接切换、事务与日志监听在 Hyperf 中都能透明地工作——它们都建立在同一套「池化 + 上下文绑定 + 事件分发」的架构之上。
小结
通过本文,你已经完成了 Hyperf 数据库组件从安装、配置到实际使用的完整闭环:掌握了 hyperf/db-connection 与 hyperf/database 的分工、默认连接与多连接的配置方式、读写分离与 sticky 的取舍、原生 SQL 的增删改查与事务(自动/手动/注解式)管理、开发期 SQL 日志记录,以及 PgSQL、SQLite、SQL Server 驱动的接入条件与配置要点。进一步阅读可参考 数据库事件、查询构建器、模型 等专题文档,深入掌握这套组件的完整能力。