一个PHP扩展的六天冲刺：从能用到敢用

一个数据库客户端的性能提升30-40%，值不值得你换掉用了多年的HTTP方案？开发者Sergey Petrunya用六天三连发给出了自己的答案。

导读

2026年4月25日，php_clickhouse 0.6.0发布，主打原生二进制协议。六天后，版本号跳到0.8.1，作者宣布"稳定"。没有功能狂欢，只有一场针对生产环境的硬核质量攻坚。

0.7.0：补齐最后一块拼图

原生协议快，但快不够。团队真正犹豫的是：换客户端要重写多少代码？

0.7.0的解法很直接——把最流行的PHP HTTP客户端（smi2/phpClickHouse）的API表面完整复刻。具体包括：

• setSettings(array) 全局配置，单次调用可覆盖
• {name:Type} 占位符实现服务端类型参数，数组类型干净往返
• 进度回调与统计信息暴露，getStatistics() 返回行数、字节、耗时等9项指标
• 结构化异常，server_code、server_name、query_id 全保留

作者的原话：「Most teams won't trade a familiar API for that, so the native client has to match the ergonomic surface」。性能是敲门砖，API兼容才是进门券。

0.8.x：把"可能崩溃"改成"一定报错"

六天的核心不是加功能，是消除三类不确定性。

内存：从指数级到常数级

插入路径重构前，内存占用是 N_rows × N_cols 个PHP变量（zvals）。重构后压到单列级别。高吞吐场景下，中间内存的峰值曲线被拉平。

输入：拒绝沉默的腐败

Map、窄整型、Int128/UInt128、地理类型、DateTime64、Time64、十六进制字面量——全部换成严格全消费解析器。类型错误抛出异常，而非静默归零或内存损坏。递归类型转换加了深度上限，防止恶意服务端schema栈溢出。

状态：从全局污染到对象隔离

早期实现把客户端状态存在文件作用域的 std::map 里。0.8.x移到 zend_object 本身。副作用：ZTS（线程安全）解锁、异常退出时的内存泄漏堵住、进度回调的引用计数bug修复。

插入失败时，原生句柄在每个服务端拒绝点恢复，抛异常不再卡死连接。

一个上游修复的意外收获

三连发期间，作者定位到clickhouse-cpp的一个未定义行为（UB），修复已合并上游。扩展的稳定性工作反哺了底层依赖。

实用指向

如果你在用PHP对接ClickHouse，检查三件事：第一，当前客户端是否还在用HTTP协议跑批量插入；第二，异常处理是否能区分服务端超时（159）和连接错误；第三，高并发场景下内存峰值是否可预测。这三项有任何一项为否，0.8.1的六天冲刺值得你花一小时迁移验证。原生二进制协议的30-40%吞吐提升是明面上的收益，真正的隐性收益是：错误行为从" undefined"变成了"defined"——生产环境最怕的不是慢，是不可预期。