Download the PHP package reactphp-x/cycle-database without Composer

reactphp-x/cycle-database

使用 ReactPHP 的 MySQL 连接池为 Cycle Database 提供异步驱动，在非阻塞环境下保持 Cycle 风格的同步 API（$db->query() / $db->execute() / 查询构建器等）。

基于组件：

• 驱动与管理：ReactphpX\CycleDatabase\AsyncDatabaseManager、AsyncMysqlDriver、AsyncMySQLDriverConfig、AsyncTcpConnectionConfig
• 查询/语句：ReactphpX\CycleDatabase\AsyncDatabase、AsyncStatement
• 依赖：reactphp-x/mysql-pool、react/async、wpjscc/database（Cycle Database 兼容实现）

特性

• 异步驱动：内部使用连接池与 React\Async\await，对外暴露同步风格接口
• 兼容 Cycle Database API：支持 select/insert/update/delete/upsert 构建器与 DatabaseInterface
• 事务（回调）：通过驱动的 transaction(callable) 以回调方式执行
• 流式查询：驱动层提供 queryStream()，适合大结果集
• 连接池：可配置最小/最大连接数、等待队列与超时

仅支持 MySQL（AsyncMysqlDriver）。

安装

要求：PHP 8.1+（代码使用 BackedEnum 等特性），MySQL 5.7+/8.0+。

快速开始（Basic）

更多可运行示例见 examples/：

• examples/mysql_basic.php
• examples/mysql_queries.php
• examples/mysql_transactions.php
• examples/mysql_upsert.php

运行示例

环境变量（可选，均有默认值）：

使用方式

同步风格查询

查询构建器（兼容 Cycle Database）

事务（使用驱动回调）

注意：不支持 begin/commit/rollback 三个方法；请使用驱动的 transaction(callable)。

流式查询（大结果集）

UPSERT 用法（updates）

• 基本语义：在 MySQL 上使用 ON DUPLICATE KEY UPDATE。当插入触发唯一键/主键冲突时转为更新。
• 默认更新列：未调用 updates() 时，默认对本次插入的所有列执行 col = VALUES(col)。
• 指定更新列：调用 updates('colA', 'colB') 仅更新给定列，其它插入列保持不变。
• 冲突列：当前 MySQL 编译器无需 conflicts()，以表上定义的唯一键/主键为准。

示例（更多见 examples/mysql_upsert.php）：

实现参考：ReactphpX\CycleDatabase\MySQLCompiler::upsertQuery() 会将未显式指定的更新列默认回落为 columns() 中的全部列。

连接池与可选项

在 AsyncMySQLDriverConfig 的 options 中传入：

• minConnections：最小连接数（默认 2）
• maxConnections：最大连接数（默认 10）
• waitQueue：等待队列容量（默认 100）
• waitTimeout：获取连接超时毫秒（默认 0，表示不超时）

驱动还提供：

• keepAlive(int $seconds = 30)：心跳保活
• close() / quit()：关闭或优雅退出

与 Cycle Database 的差异

• 使用异步驱动实现，同步外观；与官方 PDO 驱动不同
• 不支持 begin/commit/rollback 三个方法；请改用 transaction(callable)
• 仅 MySQL 实现（AsyncMysqlDriver）

API 命名与行为尽量保持与 Cycle Database 一致，迁移成本低。

License

MIT