Download the PHP package easyswoole/mysqli without Composer

EasySwoole 协程 MySQLi

基于 Swoole\Coroutine\Socket 实现的 MySQL 协议客户端，支持连接超时、单次查询的总超时、文本查询、原生服务端预处理语句，并提供 FastDb 风格的查询及事务接口；继承接口的适配要求见下文。

环境要求

• PHP 8.1 或更高版本。
• Swoole 5.1 或更高版本。
• OpenSSL、Sockets 和 zlib 扩展。
• MySQL 服务端需要 8.0。

当前暂不支持 TLS/SSL 加密连接，数据库通信使用未加密的 TCP。 无法连接要求 TLS/SSL 的 MySQL 服务端或账号；OpenSSL 扩展用于认证相关的加密操作，不代表连接已启用 TLS。

使用示例

Client::connect(?float $timeout = null) 始终使用构造函数传入的 Config 建立连接，不接受配置数组。可选参数仅指定本次建连的总超时（秒），不会修改配置；省略或传入 null 时使用 maxConnectTime。显式超时仍受 maxConnectTime 上限约束，以先到期的截止时间为准。查询方法会在需要时自动建连，也可以主动调用 connect()。

数据库操作需要在 Swoole 协程中执行：

压缩与接口兼容

compress 默认为 false。启用后，客户端通过 CLIENT_COMPRESS 协商压缩；如果服务端支持，则在认证成功后启用 zlib 压缩。如果服务端不支持，连接仍以未压缩方式继续使用。可以通过 $client->mysqlClient()->isCompressionEnabled() 查看实际协商结果。

Client::query(QueryBuilder $builder, ?float $timeout = null): bool|array 自动使用服务端预处理协议；rawQuery(string $query, ?float $timeout = null) 使用文本查询协议。两者显式声明可选超时参数，支持 timeout: 0.5 这样的命名参数。

继承 Client 的类（包括 FastDb 连接类）如果重写了 query() 或 rawQuery()，需要同步接受可选超时参数并传给父类；重写 query() 时还需要声明兼容的返回类型。旧的单参数子类方法签名不能继续使用。mysqlClient() 仅返回协议层 Connection 或 null，不再包含原生 mysqli 类型。

查询超时后，客户端会关闭连接，避免复用存在未读 MySQL 数据包的协议流。未处于事务时，下一次查询会自动重新连接。

会话安全与超时

预处理语句属于创建它的服务端会话。该会话断开或重连后，执行旧 Statement 会抛出 LogicException，需要重新 Prepare；事务丢失保护生效时优先抛出 TransactionLostException。关闭已失效的 Statement 不会关闭新会话中的语句。

连接通过服务端 OK/EOF 数据包的 SERVER_STATUS_IN_TRANS 跟踪事务，支持 BEGIN、START TRANSACTION、事务接口以及 autocommit=0 下实际开始的事务。可以通过 $client->mysqlClient()->inTransaction() 查看最近确认且连接仍有效的事务状态，通过 isTransactionLost() 查看事务是否因连接丢失而失效。普通 SQL 错误不会直接清除事务状态；InnoDB 死锁错误 1213 会同步清除已自动回滚的事务状态，锁等待超时 1205 则保留事务状态；提交、回滚及 DDL 隐式提交以服务端响应为准。

事务期间断线或查询超时，首次操作仍抛出原始连接/超时异常；后续查询、Prepare、旧 Statement 执行、Connect、Commit 和 Rollback 会抛出 EasySwoole\Mysqli\Exception\TransactionLostException，阻止透明重连后继续执行。此标记在显式 close() 前一直保留，关闭 Statement 不会解除保护。

恢复时先调用 $client->close()，再连接并开启新的事务，由业务决定是否重试整个事务。如果在 Commit 响应到达前断线，提交结果可能无法确认，不能仅凭此异常自动重放写入。

begin_transaction(TransactionStartFlags $flags = TransactionStartFlags::None) 使用 EasySwoole\Mysqli\Transaction\TransactionStartFlags 枚举。支持 None（默认）、ConsistentSnapshot、ReadWrite、ReadOnly、ConsistentSnapshotReadWrite 和 ConsistentSnapshotReadOnly。快照与访问模式通过组合枚举值表达，无需按位或；不再接受整数，旧调用需迁移为枚举，否则抛出 TypeError。例如：

commit()、rollback() 同样使用 EasySwoole\Mysqli\Transaction\TransactionCompletionFlags 枚举，默认 None。支持 Chain、NoChain、Release、NoRelease，以及组合值 ChainNoRelease、NoChainRelease、NoChainNoRelease。不再接受整数或按位或组合，旧整数调用会抛出 TypeError。枚举仅列出合法选项，不提供相互矛盾的组合。

CHAIN 后连接仍处于新事务；RELEASE 成功后本地连接同步关闭。None 不追加选项，由服务端 completion_type 决定默认结束方式；需要明确结束且保留连接时使用 NoChainNoRelease。选项语义参照 MySQL 事务语法。

文本查询和预处理结果中的 DATE 均返回 YYYY-MM-DD，DATETIME/TIMESTAMP 均返回完整的 YYYY-MM-DD HH:MM:SS。TIME、DATETIME、TIMESTAMP 按字段小数精度（0～6）保留相应位数，包括值为零的小数，例如 TIME(3) 的 00:00:00.000。TIME 保留负号和超过 24 小时的小时数，NULL 仍返回 null。

同一个连接同时只允许一个操作，包括建立连接、关闭 Statement 和关闭连接。并发调用会抛出异常，正在进行的操作仍可继续完成。可以在当前操作结束后重试关闭 Statement；需要并发查询时，应使用不同的客户端连接。

maxConnectTime 限制完整连接过程的总耗时，包括 TCP 建连、握手、认证和字符集设置。rawQuery()、query() 和 prepare() 的超时均包含必要的连接过程；query() 的 Prepare、Execute、结果读取及 Statement 清理共用同一个超时预算。连接过程同时受 maxConnectTime 限制，以先到期的截止时间为准。

超时值必须大于零。如果 Statement 清理阶段的查询预算已经耗尽，客户端会直接丢弃连接，不再为清理操作分配新的超时预算。

存储过程限制

本项目以生产应用中常见的普通 SQL、预处理查询和应用层事务为主要使用方式；在这类项目中，存储过程的使用相对较少，因此客户端暂不支持存储过程调用及多结果集。

rawQuery()、query()、prepare() 及协议连接入口会在发送调用 SQL 前拒绝 CALL，抛出 EasySwoole\Mysqli\Exception\UnsupportedOperationException。判断支持大小写、前导空白、普通注释及 MySQL 可执行注释；拒绝后原连接仍可继续使用。多结果及分号多语句能力保持关闭。

此限制仅针对本客户端调用存储过程，不修改服务端配置，也不影响其他客户端。CREATE PROCEDURE、DROP PROCEDURE 等管理语句及普通 SELECT 中的存储函数不在 CALL 限制范围内。

更多文档

• 测试命令与环境配置。
• 测试场景与验证记录。
• QueryBuilder 使用说明。

协议错误与大参数

收到格式错误或截断的协议数据时，抛出 EasySwoole\Mysqli\Exception\ProtocolException 并立即关闭连接，避免下一条查询读取遗留报文。非事务连接可在下一次查询时重新建立；事务内发生协议错误时，仍遵循上述事务丢失保护。

预处理参数采用分段编码与分包发送，避免将多个大字符串重复拼成整条执行报文。结果字段及行解码由 Protocol\ResultDecoder 负责；压缩接收缓冲区使用读取游标，减少逐行读取时的字符串复制。

内部职责划分

• Client：公开查询 API、元数据及成功回调；对外超时参数继续使用秒数。
• Connection：命令调度、认证流程和完整操作的并发保护。
• PacketStream：Socket 收发、包序号、分包重组、压缩及缓冲区；不判断事务或自动重试 SQL。
• SessionState：服务端事务状态、异常断开后的事务丢失保护、显式关闭和会话代次。
• Deadline：基于单调时钟的截止时间；连接、认证及该次命令的内部收发共享预算，建连还受 maxConnectTime 上限约束。
• ResultDecoder、ParameterEncoder、PacketPayload：结果解码、参数编码和有界发送分片。

上述辅助类属于内部实现。Client、Connection、Statement 和 QueryBuilder 的既有公开方法签名保持不变。