最靠谱的是 clickhouse-php-client（基于 HTTP 接口），轻量、兼容 PHP 7.4+ 和 8.x，支持查询/插入/参数化；避免 pdo_clickhouse、已停更的 php-clickhouse 及 C 扩展。
PHP 连 ClickHouse 用哪个扩展最靠谱？
官方不维护 PHP 原生驱动，社区主流选择是 clickhouse-php-client（基于 HTTP 接口），不是 pdo_clickhouse 或已停更的 php-clickhouse。它轻量、兼容性好、支持基本查询/插入/参数化，且能跑在 PHP 7.4+ 和 8.x 上。
- 不要尝试编译 C 扩展（如旧版
clickhouse.so），多数环境没对应版本，且 ClickHouse 官方早就不推荐非 HTTP 方式直连 PHP -
curl+ 手写 HTTP 请求也能连，但得自己处理 JSON 编码、错误响应、超时重试——没必要重复造轮子 -
clickhouse-php-client底层就是curl，但它封装了常见模式，比如自动加?database=xxx、统一处理HTTP 400错误体里的Code: 60（表不存在）
怎么装 clickhouse-php-client 并初始化连接？
用 Composer 装，别手动下载：
composer require sapientech/clickhouse-php-client
初始化时注意三点：
-
host写 IP 或域名，不要带http://前缀（构造器内部会拼） -
port默认是8123（HTTP 接口），不是9000（TCP 接口，PHP 不走这个） -
username/password要和 ClickHouseusers.xml或config.xml里配的一致；若未设密码，留空字符串''，别传null
示例：
立即学习“PHP免费学习笔记（深入）”；
use Sapientech\ClickHouse\Client;$client = new Client([ 'host' => '192.168.1.100', 'port' => 8123, 'username' => 'default', 'password' => '', 'database' => 'test', ]);
INSERT 数据为什么总报 Code: 27，不能直接 bindParam？
clickhouse-php-client 的 insert() 方法不支持传统 PDO 那种占位符绑定，必须传二维数组（每行一条记录），且字段顺序要和建表语句严格一致。
常见错误现象：
- 传一维数组 → 报
Code: 27. DB::Exception: Cannot parse input - 字段名写错或漏字段 → 同样是
Code: 27或Code: 457（类型不匹配） - 时间字段传 PHP
DateTime对象 → ClickHouse 拒收，得转成'Y-m-d H:i:s'字符串或时间戳
正确写法：
$data = [
['id' => 1001, 'name' => 'foo', 'created_at' => date('Y-m-d H:i:s')],
['id' => 1002, 'name' => 'bar', 'created_at' => date('Y-m-d H:i:s')],
];
$client->insert('users', $data);
注意：这里 users 是表名，$data 里键名只是示意，实际插入时只认顺序，不认键名（底层按列位置写入）。所以更稳妥的是传索引数组：
$data = [
[1001, 'foo', '2024-06-01 10:20:30'],
[1002, 'bar', '2024-06-01 10:20:31'],
];
$client->insert('users', $data);
查询结果怎么取？fetchOne 和 fetchAll 区别在哪？
-
fetchOne() 返回第一行（一维数组），适合 SELECT count()... 这类单值查询
-
fetchAll() 返回全部行（二维数组），每行是关联数组，键为字段名
- 没有
fetchColumn()，想取单列得自己 array_column($rows, 'col_name')
fetchOne() 返回第一行（一维数组），适合 SELECT count()... 这类单值查询fetchAll() 返回全部行（二维数组），每行是关联数组，键为字段名fetchColumn()，想取单列得自己 array_column($rows, 'col_name')
执行后不检查返回值直接用，容易出 Notice：
- 查询无结果时
fetchOne()返回null，直接['id']会报Trying to access array offset on value of type null -
fetchAll()空结果返回空数组[]，不是false，别用if (!$rows)判空（这是错的）
建议写法：
$result = $client->select("SELECT id, name FROM users WHERE id = ?", [1001]);
if ($result && $row = $result->fetchOne()) {
echo $row['id'];
}
ClickHouse 的 HTTP 接口默认不返回字段类型信息，所以 fetch* 返回的全是字符串——数值、日期都得自己 (int) 或 strtotime() 转。这点和 MySQLi/PDO 行为不同，容易忽略。
