Hyperf 数据库快速上手:连接池、读写分离、多库配置与原生 SQL 执行全指南

原创2026-10-07 12:19:012,142 阅读
文章标签:后端微服务RPC框架Web框架

Hyperf 数据库快速上手:连接池、读写分离、多库配置与原生 SQL 执行全指南

导读

本文以 Hyperf 官方文档「数据库快速开始」(docs/id/db/quick-start.md)为骨架,系统讲解在 Hyperf 中接入关系型数据库的完整链路:从安装 hyperf/db-connection、编写 config/autoload/databases.php 配置,到使用 Db 门面执行原生 SQL、开启读写分离与多库连接、管理事务,再到 PgSQL/SQLite/SQL Server 等扩展驱动。读完本文,你将能够独立完成 Hyperf 项目的数据库初始化、连接池调优、主从库切换与事务落地,并理解底层连接池与协程上下文的工作机制。

组件关系:hyperf/database 与 hyperf/db-connection

hyperf/database 组件源自 Laravel 的 illuminate/database,Hyperf 团队对其进行了改造,使其能够运行在普通 PHP-FPM 框架以及基于 Swoole 的协程框架中,大部分 API 与使用习惯保持不变。

而在 Hyperf 中实际使用数据库时,还必须引入 hyperf/db-connection。该组件承担「桥梁」角色:

  • 基于 hyperf/pool 实现数据库连接池;
  • 为模型提供新的抽象基类;
  • 将数据库组件与事件组件(Event)打通,让 Hyperf 能够监听查询执行、事务提交等生命周期事件。

这一点在源码中可以得到印证:hyperf/db-connection 的 ConnectionResolver.php 从连接池工厂获取连接,并借助 Hyperf\Context\Context 将连接对象绑定到当前协程上下文,协程结束(或通过 defer 延迟回调)时自动把连接归还连接池。这正是 Hyperf 数据库连接能够在协程间隔离、复用的核心机制。

安装

在 Hyperf 框架中安装

composer require hyperf/db-connection

在其他框架中使用

如果项目不是 Hyperf,而是其他 PHP-FPM 或 Swoole 框架,则只需安装数据库核心组件:

composer require hyperf/database

数据库配置

默认配置与参数说明

配置位于 config/autoload/databases.php,支持多数据库,其中 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),
        ]
    ],
];

从源码角度看,连接池的参数解析发生在 DbPool.php:它从配置中心读取 databases.{name} 段,并把其中的 pool 数组直接传给 Hyperf\Pool\Pool 基类。因此 min_connections、max_connections、connect_timeout、wait_timeout、heartbeat、max_idle_time 均作用于连接池的伸缩、排队与保活行为——在高并发协程场景下,max_connections 决定了可同时活跃的数据库连接上限,而 wait_timeout 控制连接耗尽时调用方的等待时长。

自定义 PDO 选项

有时需要调整 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,
        ],
    ],
];

配置中的 options 数组会经由 ConnectionFactory.php 的 PDO 解析闭包最终传入 PDO 构造器。需要注意的是:默认 PDO::ERRMODE_EXCEPTION 意味着 SQL 执行出错会直接抛出异常,业务代码应据此做好异常捕获;ATTR_EMULATE_PREPARES 在云数据库等不支持原生预处理协议的场景下必须调整为 true。

读写分离(Read/Write Splitting)

当 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),
        ],
    ],
];

注意上述示例在配置数组中新增了三个 key:read、write 和 sticky。read 与 write 内部都是一个包含 host 的数组;除 host 外,其余数据库配置(用户名、密码、表前缀、字符集等)均从主配置数组共享。如果需要覆盖主数组中的某些配置,直接在 read/write 数组中重写即可。上面的例子中,192.168.1.1 将作为读连接 host,196.168.1.2 作为写连接 host,两者共享 mysql 主配置里的凭据与编码等。

sticky 是可选的布尔值,用于决定是否在同一个请求周期内立即读取刚写入的数据:启用 sticky 后,若当前请求周期内已发生写操作,后续读操作将复用写连接,从而避免因主从复制延迟导致「写后读不到」的数据不一致问题。是否启用取决于业务对一致性的要求。

在底层,ConnectionFactory.php 的 make() 会检测配置中是否存在 read 段,存在时调用 createReadWriteConnection():先基于写配置创建主连接,再通过 setReadPdo() 注入一个读 PDO 解析闭包。读连接只会在执行读语句时惰性建立,且当 read.host 以数组形式给出多个地址时,会通过 Arr::random 随机选取并在连接失败时自动轮换下一个 host。

多数据库配置(Multiple Databases)

多数据库配置示例如下:

<?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),
        ],
    ],
];

使用时,将连接名指定为 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 属性指定连接。下面的 User 模型使用了 test 配置:

<?php

declare(strict_types=1);

namespace App\Model;

/**
 * @property int $id
 * @property string $mobile
 * @property string $realname
 */
class User extends Model
{
    /**
     * 模型关联的表。
     *
     * @var string
     */
    protected $table = 'user';

    /**
     * 模型使用的连接名。
     *
     * @var string
     */
    protected $connection = 'test';

    /**
     * 允许批量赋值的属性。
     *
     * @var array
     */
    protected $fillable = ['id', 'mobile', 'realname'];

    /**
     * 需要转为原生类型的属性。
     *
     * @var array
     */
    protected $casts = ['id' => 'integer'];
}

补充说明:Hyperf 中的模型基类位于 src/db-connection/src/Model/Model.php,它在 Hyperf\Database\Model\Model 基础上混入了容器访问与仓储(Repository)相关 trait,实际使用中你只需继承 Hyperf\DbConnection\Model\Model(或项目骨架生成的 App\Model\Model)。模型内指定的 $connection 最终通过查询构建器透传到对应名称的连接池。

执行原生 SQL

完成数据库配置后,即可通过 Hyperf\DbConnection\Db 执行查询。Db.php 是一个静态门面:__callStatic 会先从容器取出 Db 实例,再转发到默认连接上同名方法;connection($name) 则通过 ConnectionResolver 返回指定连接。

查询类(Query Class)

主要覆盖 SELECT、带有 READS SQL DATA 属性的存储过程、函数以及其他查询类语句。select 方法始终返回数组,数组中的每个结果是 StdClass 对象:

<?php

use Hyperf\DbConnection\Db;

$users = Db::select('SELECT * FROM `user` WHERE gender = ?', [1]);  // 返回数组

foreach ($users as $user) {
    echo $user->name;
}

执行类(Execute Class)

主要覆盖 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 属性的存储过程

与 select 不同,insert/statement 返回布尔值,update/delete 返回受影响行数——这与 Db.php 中标注的 @method 返回类型完全一致,可在 IDE 中直接获得类型提示。

事务自动管理

使用 Db 的 transaction 方法,在 Closure 内执行操作:一旦闭包内抛出异常,事务自动回滚;全部成功则自动提交,无需手动处理:

<?php

use Hyperf\DbConnection\Db;

Db::transaction(function () {
    Db::table('user')->update(['votes' => 1]);

    Db::table('posts')->delete();
});

底层实现在 ManagesTransactions.php:transaction() 先 beginTransaction(),回调成功则 commit(),捕获异常则回滚;若异常由死锁(deadlock)引起且还有剩余尝试次数,还会自动重试(transaction 的第二个参数 $attempts 控制最大尝试次数,默认 1)。MySQL 在死锁时会回滚整个事务,因此重试仅当嵌套事务(transactions > 1)时才会被阻止并直接抛出。

事务手动管理

需要完全掌控事务时,可用 Db 的 beginTransaction、commit、rollBack 手动管理:

<?php

use Hyperf\DbConnection\Db;

Db::beginTransaction();
try {
    // 执行你的操作...

    Db::commit();
} catch (\Throwable $ex) {
    Db::rollBack();
}

需要特别提醒:在连接池场景下,连接归还时会检查事务层级。从 Connection.php 的 release() 逻辑可以看到,若连接归还时仍处于事务中(transactionLevel() > 0),组件会自动回滚并输出错误日志「Maybe you've forgotten to commit or rollback the MySQL transaction.」——因此务必在协程结束前提交或回滚事务,避免把未提交的事务随连接一起归还连接池。

打印刚执行的 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()、getQueryLog() 定义于 src/database/src/Connection.php:开启后,每次查询执行都会把 SQL、绑定参数与耗时追加到内存日志数组,且不设上限,这正是官方文档提示生产环境禁用(防止内存泄漏)的原因。

支持的驱动列表

与 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'),
    ]
];

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'),
        'database' => env('DB_DATABASE', ':memory:'),
        // :memory: 表示内存数据库,也可以填写绝对文件路径
        // 其他 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,
    ]
];

从源码理解连接池与协程的协作

最后,把配置与源码串起来看,Hyperf 数据库连接的整体工作流程如下:

  1. 应用启动后,DbPool 依据 config/autoload/databases.php 中 databases.{连接名} 段初始化连接池(DbPool.php),并将 pool 配置交给通用连接池基类管理;
  2. 协程中调用 Db::select() 等静态方法时,Db 门面经 ConnectionResolver 解析:先从协程上下文(Context)中取当前协程已持有的连接,没有则向连接池 get() 借出连接并绑定到上下文(ConnectionResolver.php);
  3. 协程结束(或通过 defer 延迟注册)时,连接归还连接池;归还前若发现事务未结束会自动回滚,错误计数超过 100 的连接会在下次取用时强制重建(Connection.php);
  4. 断线重连由 Connection 的 reconnect() 与 refresh() 完成:重建 PDO 后会重新绑定事件分发器与重连回调,保证长连接失效时能平滑恢复。

理解这一链路后,你就能针对高并发场景合理配置 pool.max_connections、wait_timeout 与 heartbeat,并在读写分离、多库切换之间游刃有余。继续深入可以阅读仓库中的 数据库模型、查询构建器、迁移 与 数据库事件 等文档。

登录后查看全文
hyperf