Hyperf 数据库组件快速上手:连接池、读写分离、事务与原生 SQL 实战指南

原创2026-10-11 11:40:521,604 阅读
文章标签:后端微服务RPC框架Web框架

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 提供带死锁重试的自动事务。进一步深入学习,可以继续阅读仓库中的 模型文档、查询构造器文档、迁移文档 以及 数据库事件文档。

登录后查看全文
hyperf