应直接使用 smi2/phpclickhouse，它纯 PHP 实现、协程安全、持续维护，兼容 ClickHouse v23+ 与 PHP 8.0+；禁用 keep_alive、port 必须为字符串、database 仅指定默认库名，流式查询需用 selectStream() 并设 set_time_limit(0)。
Hyperf 里别用 swoole-clickhouse 驱动
直接放弃 swoole-clickhouse —— 它已三年未更新（最后 commit 在 2023 年），不兼容 ClickHouse v22+ 的 HTTP 接口变更，且与 Hyperf 的协程上下文管理存在隐式冲突，insert() 后查不到数据、连接复用时偶发 cURL error 7（Failed to connect to host）都是高频现象。
根本原因在于：该驱动强行 patch cURL 句柄做协程化，但没处理 ClickHouse 返回的 chunked 响应流、HTTP/1.1 keep-alive 复用逻辑，以及 Hyperf 2.2+ 默认启用的 Coroutine::set(['hook_flags' => SWOOLE_HOOK_ALL]) 下的 socket 状态同步问题。
替代方案只有两个：smi2/phpclickhouse（推荐）或原生 cURL 封装。前者是纯 PHP 实现，完全协程安全；后者需手动加 Co\run() 包裹，易漏。
用 smi2/phpclickhouse 适配 Hyperf 协程
它本身不感知协程，但在 Hyperf 中能稳定运行，关键在三点配置：
- 必须在
config/autoload/services.php中注册为单例，避免每次 new 出新连接实例导致连接池失效 - 禁用
keep_alive（设'keep_alive' => false），因为 Hyperf 的协程 DNS 缓存与该驱动的 cURL 复用逻辑不兼容，会卡在getaddrinfo阶段 -
port必须是字符串，例如'port' => '8123'，写成整数8123会导致http_build_query()把它转为空字符串，最终请求发到http://host:/而失败
最小可用配置示例：
$client = new \ClickHouseDB\Client([
'host' => 'clickhouse.internal',
'port' => '8123',
'username' => 'default',
'password' => '',
'database' => 'olap',
'timeout' => 45,
'keep_alive' => false,
]);
在 Command 或 Listener 中调用 ClickHouse 的坑
Hyperf 的 Command 默认不在协程环境，直接 new Client 会走同步 cURL，阻塞整个进程；Listener 虽在协程中，但若未显式 Co\run() 包裹，部分生命周期钩子（如 OnWorkerStart）仍可能退化为同步调用。
正确做法是统一用 Co\run() 包一层，哪怕只跑一条 select()：
Co\run(function () {
$client = make(\ClickHouseDB\Client::class);
$result = $client->select('SELECT count() FROM events WHERE dt >= today() - 7');
var_dump($result->rows());
});
常见错误现象：
-
PHP Warning: curl_setopt(): cannot set CURLOPT_TIMEOUT_MS in vendor/smi2/phpclickhouse/src/Transport/Curl.php：说明当前 PHP 版本 'timeout' => 45（秒级）代替 - 查询返回空数组但无报错：检查
database是否拼错，该参数不用于登录鉴权，仅指定默认库名；如果表在analytics库而你设了'database' => 'olap'，又没在 SQL 中写analytics.table，就会查不到
大结果集导出时内存暴涨
ClickHouse 的 SELECT 默认返回全部结果，Hyperf Worker 进程内存会随行数线性增长。10 万行文本数据轻松吃掉 200MB+ 内存，触发 OOM kill。
必须启用流式读取：
- 改用
$client->selectStream()，它返回Generator，每行 yield 一次 - 禁止在 stream 回调里做耗时操作（如写文件、发 HTTP），否则阻塞协程调度
- 若需保存到本地 CSV，用
fopen('php://temp', 'w+')临时内存文件，比fopen('/tmp/x.csv', 'w')更快且不占磁盘 I/O
示例片段：
$stream = $client->selectStream('SELECT * FROM events LIMIT 100000');
foreach ($stream as $row) {
fputcsv($fp, $row); // $fp 是 php://temp 打开的句柄
}
真正容易被忽略的是：ClickHouse 的 HTTP 接口对流式响应没有长度限制，但 Hyperf 默认的 max_execution_time 会中断长请求。必须在命令入口处加 set_time_limit(0)，否则 30 秒后进程直接退出，CSV 只写一半。
