PHP连接ClickHouse数据库教程

哈喽！今天心血来潮给大家带来了《PHP连接ClickHouse数据库步骤详解》，想必大家应该对文章都不陌生吧，那么阅读本文就都不会很困难，以下内容主要涉及到，若是你正在学习文章，千万别错过这篇文章~希望能帮助到你！

推荐使用 clickhouse-cpp 扩展连接 ClickHouse，它基于官方 C++ 客户端、支持 HTTP 协议（默认8123端口），性能稳定；禁用 mysqli/PDO_PGSQL 等不兼容协议；需正确配置字符集、时区及 NULL 表示（"\N"）。

用 clickhouse-cpp 扩展连接 ClickHouse（推荐方式）

PHP 官方不提供原生 ClickHouse 驱动，最稳定、性能最好的选择是编译安装 clickhouse-cpp 扩展（C++ 编写，基于官方客户端库）。它支持 HTTP 协议（默认端口 8123），无需额外代理层。

常见错误：直接用 mysqli 或 PDO_PGSQL 尝试连接 —— ClickHouse 不兼容 MySQL/PostgreSQL 协议，会报 Connection refused 或 Unknown database 类错误。

• 确认 ClickHouse 服务已启用 HTTP 接口：grep -i "http_port" /etc/clickhouse-server/config.xml（默认为 8123）
• 安装依赖：apt install build-essential cmake libssl-dev（Ubuntu/Debian）
• 克隆并编译扩展：git clone https://github.com/smi2/php-clickhouse && cd php-clickhouse && phpize && ./configure && make && sudo make install
• 启用扩展：在 php.ini 中添加 extension=clickhouse.so，然后重启 PHP-FPM 或 Apache

ClickHouseClient 实例化与基础查询

扩展加载成功后，用 ClickHouseClient 类发起请求。它默认走 HTTP，不支持长连接复用，每次查询都是独立请求 —— 这不是 bug，是设计使然。

注意：不支持预处理语句（prepare/execute），所有参数需手动拼接或使用 addParam 做简单替换（仅限标量值）。

• 基本连接：$client = new ClickHouseClient(['host' => '127.0.0.1', 'port' => 8123, 'database' => 'default']);
• 执行 SELECT：$client->select('SELECT count() FROM system.tables')->rows(); 返回二维数组
• 插入数据（单条）：$client->insert('test_table', [['id' => 1, 'name' => 'foo']], ['id', 'name']);
• 批量插入建议用 insertBatch，否则每行都发一次 HTTP 请求，性能极差

用 curl 或 file_get_contents 手动发 HTTP 请求（备用方案）

若无法编译扩展（如共享主机环境），可绕过扩展，直接调用 ClickHouse 的 HTTP 接口。本质就是 POST 一个 SQL 字符串到 http://host:8123/。

容易踩的坑：没设 Content-Type: text/plain; charset=utf-8，或没 URL 编码 SQL，导致中文字段名/值解析失败；漏掉 user 参数导致 403。

• 最小可行示例：$sql = urlencode('SELECT * FROM system.one'); $url = "http://127.0.0.1:8123/?query={$sql}&user=default"; echo file_get_contents($url);
• 带参数查询（避免 SQL 拼接）：POST /?query=SELECT+*+FROM+logs+WHERE+date+%3D+{date:String} HTTP/1.1，然后在 body 中传 date=2024-01-01
• 返回格式控制：加 &format=JSONEachRow 获取流式 JSON 行，比默认的 TabSeparated 更易解析

字符集、时区和 NULL 处理的隐性约束

ClickHouse 默认不校验字符集，但 PHP 侧若用 UTF-8 以外编码（如 GBK）发请求，会导致乱码或语法错误；时区不一致则 now()、分区键计算结果偏差；NULL 值在 HTTP 接口中只能表示为 \N 字符串，不能传 null。

• 强制指定客户端时区：?timezone=Asia/Shanghai（加在 URL 查询参数中）
• 插入含 NULL 字段的数据时，字段值必须为字符串 "\\N"（注意 PHP 中双引号需转义）
• 日期字段建议统一用 Date32 或 DateTime64 类型，并在 SQL 中显式转换：toDate('2024-01-01')
• 大结果集别用 select() 直接取全部，改用 selectStream() 或分页 LIMIT/OFFSET，否则内存爆掉

HTTP 接口看似简单，但字符编码、时区、NULL 表示、批量写入效率这些点，线上出问题时往往查半天才意识到是协议层语义没对齐。

今天关于《PHP连接ClickHouse数据库教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！