Hyperf 数据库快速上手:hyperf/database 连接池、读写分离与原生 SQL 实战全解

原创2026-10-08 19:01:292,616 阅读
文章标签:后端微服务

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 实现,因此无需修改框架核心代码即可扩展新的数据库引擎。

登录后查看全文
hyperf