17370845950

最靠谱的是 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 请求也能连，但得自己处理 J

  

  SON 编码、错误响应、超时重试——没必要重复造轮子
• 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 要和 ClickHouse users.xml 或 config.xml 里配的一致；若未设密码，留空字符串 ''，别传 null

示例：

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', '2025-06-01 10:20:30'],
    [1002, 'bar', '2025-06-01 10:20:31'],
];
$client->insert('users', $data);

查询结果怎么取？fetchOne 和 fetchAll 区别在哪？

• 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 行为不同，容易忽略。