Hyperf 数据库快速入门:从安装配置到连接池、读写分离与事务实战

原创2026-10-07 11:44:151,687 阅读
文章标签:后端微服务

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 驱动的接入条件与配置要点。进一步阅读可参考 数据库事件、查询构建器、模型 等专题文档,深入掌握这套组件的完整能力。

登录后查看全文
hyperf