ClickHouse作为一款高性能的列式数据库，在OLAP场景下表现非常抢眼，越来越多的PHP项目开始在报表统计、日志分析等模块中引入它。但PHP连接ClickHouse的方式和连接MySQL完全不同，没有现成的mysqlnd式扩展可以直接加载，初次接触时容易在连接环节上浪费不少时间。本文会从环境准备到实际代码，完整梳理PHP接入ClickHouse的实施方案。
ClickHouse连接方式的选择与解析
在动手写代码之前，先要理解ClickHouse对外提供的访问通道。ClickHouse本身是一个独立部署的数据库服务，它没有提供类似MySQL的二进制协议给PHP使用，主流的接入路径有两条：一条是使用官方维护的clickhouse-php-client库，这个库底层仍然通过HTTP接口通信，但对请求封装和结果解析做了完善的封装；另一条是直接使用PHP的cURL扩展或Guzzle HTTP客户端，手动构造点击house的HTTP请求，这种方式更轻量，适合只需要执行少量SQL的场景。
选择哪种方式主要取决于项目需求。如果项目中需要频繁操作ClickHouse数据表，比如做每日报表的批量写入、定时任务中的ETL流程，建议使用官方客户端库，它提供了查询构建器、批量插入优化、结果集映射等功能，开发效率更高。如果只是偶尔做一次数据校验，或者在一个小工具脚本中查询一下，直接发HTTP请求反而更省事，不需要引入额外依赖。
无论选哪种方式，连接ClickHouse时都需要掌握几个关键信息：服务器地址、HTTP端口（默认8123）、用户名和密码（默认用户default通常无密码）、目标数据库名称。这些参数在连接代码中都是必需的。
环境准备与依赖安装
PHP连接ClickHouse前，需要确认本机PHP环境已经安装了必要的扩展。由于ClickHouse的HTTP接口返回的数据默认是JSON格式，PHP端解析JSON需要json扩展（PHP 8.0以后默认内置），发送HTTP请求则依赖cURL扩展，这两个是基础。可以在终端执行以下命令检查扩展是否已安装：
php -m | grep curl php -m | grep json
如果cURL扩展缺失，在Ubuntu系统中可以通过包管理工具直接安装，命令示例如下：
sudo apt-get update sudo apt-get install php-curl
接下来需要安装官方提供的clickhouse-php-client库。该库已经发布到Packagist，推荐使用Composer来管理依赖，在项目根目录执行以下命令即可完成安装：
composer require clickhouse/clickhouse-php-client
安装完成后，Composer会自动生成vendor目录及autoload文件，后续在代码中引入autoload即可使用客户端类。如果你不想用Composer，也可以从GitHub上手动下载源码包并注册自动加载，但不推荐这样做，因为依赖管理会比较混乱。
使用官方PHP客户端建立连接
官方客户端库的结构清晰，核心类是ClickHouseDB\Client，它封装了连接配置、SQL执行、数据导入导出等能力。先看一个最基础连接的代码示例：
<?php
require_once __DIR__ . '/vendor/autoload.php';
use ClickHouseDB\Client;
$config = [
'host' => '127.0.0.1',
'port' => '8123',
'username' => 'default',
'password' => '',
'database' => 'default',
'timeout' => 10,
];
$client = new Client($config);
// 测试连接是否正常
$client->ping();
echo "连接成功" . PHP_EOL;
这段代码完成了三件事：加载Composer自动加载器、配置连接参数、通过ping方法测试连通性。如果ClickHouse服务正常启动且端口没有被防火墙拦截，页面上会输出连接成功。这里需要说明的是，ClickHouse的8123端口是HTTP接口专用，如果服务器上同时还开启了9000端口的原生协议，PHP并不能直接使用它，因为那是给clickhouse-client命令行工具使用的。
连接建立之后，就可以执行SQL语句了。客户端的select方法用于查询，返回值中包含rows（结果数组）、totals（聚合结果）、statistics（执行统计）等字段。下面是一个完整的查询示例，先创建一张测试表，再插入一条数据，最后查询出来：
<?php
$client->write("
CREATE TABLE IF NOT EXISTS test.visits (
id UInt32,
user_name String,
visit_time DateTime
) ENGINE = MergeTree()
ORDER BY id
");
$client->insert(
'test.visits',
[
[1, '张三', '2025-06-01 10:30:00'],
[2, '李四', '2025-06-01 11:00:00'],
],
['id', 'user_name', 'visit_time']
);
$result = $client->select("SELECT * FROM test.visits");
foreach ($result->rows() as $row) {
echo $row['user_name'] . ' - ' . $row['visit_time'] . PHP_EOL;
}
插入数据时，insert方法的第二个参数是二维数组，每一行对应一条记录，字段顺序要和第三个参数指定的列名顺序保持一致。rows()方法返回的是一个生成器，对于大批量查询结果，这种方式可以显著降低内存占用，不会一次性把所有数据加载到内存中。
通过HTTP接口手动连接ClickHouse
有些场景下不想引入第三方依赖，比如在服务器的运维脚本里，直接使用cURL配合PHP内置函数就可以完成与ClickHouse的交互。ClickHouse的HTTP接口接受GET和POST请求，SQL语句通过query参数传递。下面这段代码演示了使用cURL发送查询请求的完整流程：
<?php
$host = '127.0.0.1';
$port = '8123';
$database = 'default';
$username = 'default';
$password = '';
$sql = "SELECT 1 AS test, 'hello' AS message";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://{$host}:{$port}/?database={$database}");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $sql);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-ClickHouse-User: ' . $username,
'X-ClickHouse-Key: ' . $password,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Curl error: ' . curl_error($ch);
} else {
// 默认返回JSON格式数据
$data = json_decode($response, true);
print_r($data);
}
curl_close($ch);
这段代码的关键点在于，POST请求的body直接放SQL语句，用户名和密码通过请求头传递。ClickHouse默认返回JSON格式的结果集，如果查询是SELECT语句，返回结构包含meta、data、rows、statistics等字段。对于非查询的DDL或DML语句，HTTP状态码为200即表示执行成功。
手动HTTP方式虽然灵活，但需要注意几个问题：一是返回数据量大时，json_decode可能内存暴涨，可考虑流式读取；二是写法比较原始，每次执行SQL都要重复构建cURL逻辑；三是错误处理不够智能，比如SQL语法报错时，HTTP状态码虽然是200，但响应体里会包含异常信息text字段，需要自己额外做解析判断。因此这种方式更适合快速测试接口连通性，或者做临时的数据捞取工具。
常见连接问题排查思路
PHP连不上ClickHouse时，报错信息五花八门，这里整理几个高频问题的排查方法。首先是端口不通，telnet测试一下8123端口是否开放：
telnet 127.0.0.1 8123
如果连接失败，先检查ClickHouse服务是否已启动，可以看进程列表：
ps -ef | grep clickhouse
服务在运行但端口不通，多半是防火墙拦截了入站请求，Ubuntu系统中可以使用ufw allow 8123放行端口。HTTP连接出现401错误时，说明身份认证未通过，需要核对用户名和密码是否匹配。ClickHouse安装完成后，默认user为default且没有密码，如果生产环境修改过配置，则必须使用正确的凭据。数据库名不存在时，查询语句会返回404错误码，比如连接配置中指定了不存在的database，这个问题通过建库语句就能解决。
另一个容易踩的坑是注意转义问题。当SQL语句中包含反斜杠或单引号时，在PHP双引号字符串中需要额外小心，推荐使用单引号定义SQL字符串，或者使用heredoc结构化写法。举个例子，Windows环境下导入数据时路径中带反斜杠，类似C:\ASR\data.csv，如果直接放在PHP双引号字符串里，反斜杠会被当作转义字符处理，导致SQL异常，此时应该使用单引号括起来或者对反斜杠再转义一次。
连接池与性能优化建议
ClickHouse处理单条查询的速度很快，但建立HTTP连接本身有开销，频繁创建连接会拖慢整体性能。PHP-FPM模式下每个请求生命周期较短，连接复用价值有限，但在常驻内存的Swoole或Workerman服务中，连接池就显得非常重要。官方客户端没有内置连接池机制，不过可以在应用层自己实现一个简单的连接池，核心思路是预先创建一组Client实例，通过队列来管理空闲和忙碌状态，请求结束后归还连接。
一个简化版的连接池实现思路如下：
<?php
class ClickHousePool
{
private array $pool = [];
private array $inUse = [];
private int $maxSize;
public function __construct(private array $config, int $maxSize = 10)
{
$this->maxSize = $maxSize;
}
public function get(): ClickHouseDB\Client
{
if (!empty($this->pool)) {
$client = array_pop($this->pool);
$this->inUse[spl_object_id($client)] = $client;
return $client;
}
if (count($this->inUse) < $this->maxSize) {
$client = new ClickHouseDB\Client($this->config);
$this->inUse[spl_object_id($client)] = $client;
return $client;
}
throw new RuntimeException('连接池资源耗尽');
}
public function put(ClickHouseDB\Client $client): void
{
$id = spl_object_id($client);
if (isset($this->inUse[$id])) {
unset($this->inUse[$id]);
$this->pool[] = $client;
}
}
}
数据写入方面，ClickHouse官方推荐使用大batch批量写入，而不是逐条insert。每批建议5000到50000行，数据格式可以使用JSONEachRow，服务端解析效率更高。官方客户端提供insertAssocBulk方法支持批量关联数组插入，配合压缩传输可以进一步降低网络IO。
最后关于超时设置，OLAP查询很可能执行时间较长，HTTP客户端默认超时只有30秒，如果业务中有跑大范围聚合查询的需求，务必把timeout参数调到60秒甚至更长。同时也要注意先设置ClickHouse服务端的max_execution_time参数，避免个别慢查询拖垮整个服务。配置文件路径通常在/etc/clickhouse-server/config.xml中，修改后需要重启服务才能生效。
PHPClickHouse数据库连接修改时间：2026-08-28 16:39:41