PHP ClickHouse客户端完整使用指南：5分钟快速上手

PHP ClickHouse客户端完整使用指南：5分钟快速上手

【免费下载链接】phpClickHousephp ClickHouse wrapper项目地址: https://gitcode.com/gh_mirrors/ph/phpClickHouse

phpClickHouse 是一个功能强大的 PHP ClickHouse 客户端库，为开发者提供了与 ClickHouse 列式数据库进行高效交互的完整解决方案。该库基于纯 PHP 实现，仅依赖 Curl 扩展，支持 PHP 8.0 及以上版本，是构建高性能数据分析应用的理想选择。

快速安装与配置

安装步骤

通过 Composer 快速安装 phpClickHouse：

composer require smi2/phpclickhouse

基础连接配置

建立与 ClickHouse 数据库的连接非常简单：

require 'vendor/autoload.php'; use ClickHouseDB\Client; $config = [ 'host' => '192.168.1.1', 'port' => '8123', 'username' => 'default', 'password' => '', 'https' => true ]; $db = new Client($config); $db->database('default'); // 测试连接状态 if ($db->ping()) { echo '连接成功！'; } else { echo '数据库连接失败'; }

核心功能特性详解

异步查询处理

phpClickHouse 支持异步查询执行，可以显著提升查询效率：

// 创建异步查询 $state1 = $db->selectAsync('SELECT 1 as ping'); $state2 = $db->selectAsync('SELECT 2 as ping'); // 批量执行异步查询 $db->executeAsync(); // 获取查询结果 print_r($state1->rows()); print_r($state2->fetchOne('ping'));

批量数据插入

对于大数据量的插入操作，phpClickHouse 提供了高效的批量插入功能：

// 插入多行数据 $stat = $db->insert('summing_url_views', [ [time(), 'HASH1', 2345, 22, 20, 2], [time(), 'HASH2', 2345, 12, 9, 3], [time(), 'HASH3', 5345, 33, 33, 0], ], ['event_time', 'site_key', 'site_id', 'views', 'v_00', 'v_55'] );

HTTP 压缩优化

启用 HTTP 压缩可以大幅减少网络传输数据量：

$db->settings()->max_execution_time(200); $db->enableHttpCompression(true); // 执行压缩后的批量插入 $result_insert = $db->insertBatchFiles('summing_url_views', $file_data_names, [...]); foreach ($result_insert as $fileName => $state) { echo $fileName . ' => ' . json_encode($state->info_upload()) . PHP_EOL; }

高级查询功能

条件模板查询

使用条件模板可以构建动态 SQL 查询：

$db->enableQueryConditions(); $input_params = [ 'select_date' => ['2000-10-10', '2000-10-11', '2000-10-12'], 'limit' => 5, 'from_table' => 'table' ]; $select = ' SELECT * FROM {from_table} WHERE {if select_date} event_date IN (:select_date) {else} event_date=today() {/if} {if limit} LIMIT {limit} {/if} '; $statement = $db->selectAsync($select, $input_params); echo $statement->sql();

数组类型支持

phpClickHouse 完全支持 ClickHouse 的数组数据类型：

$db->write(' CREATE TABLE IF NOT EXISTS arrays_test_string ( s_key String, s_arr Array(String) ) ENGINE = Memory '); $db->insert('arrays_test_string', [ ['HASH1', ["a", "dddd", "xxx"]], ['HASH1', ["b'\tx"]], ], ['s_key', 's_arr'] );

集群管理功能

集群配置与监控

phpClickHouse 提供了完整的 ClickHouse 集群管理功能：

$config = [ 'host' => 'cluster.clickhouse.dns.com', 'port' => '8123', 'username' => 'default', 'password' => '' ]; $cl = new ClickHouseDB\Cluster($config); $cl->setScanTimeOut(2.5); // 设置节点扫描超时时间 // 检查副本状态 if (!$cl->isReplicasIsOk()) { throw new Exception('副本状态异常，错误信息：'.$cl->getError()); } // 获取集群信息 print_r($cl->getNodes()); print_r($cl->getClusterList());

表分区操作

管理 ClickHouse 表分区：

$count_result = 2; print_r($db->partitions('summing_partions_views', $count_result);

实用开发技巧

查询结果处理

phpClickHouse 提供了多种结果处理方式：

$statement = $db->select('SELECT * FROM summing_url_views LIMIT 2'); // 获取行数统计 echo "查询行数：" . $statement->count(); echo "总行数：" . $statement->countAll(); // 提取单行数据 print_r($statement->fetchOne()); // 获取统计信息 print_r($statement->statistics());

流式数据处理

对于大数据量的读写操作，可以使用流式处理：

// 流式写入 $streamWrite = new ClickHouseDB\Transport\StreamWrite($stream); $client->streamWrite($streamWrite, 'INSERT INTO {table_name} FORMAT JSONEachRow', ['table_name'=>'_phpCh_SteamTest']); // 流式读取 $streamRead = new ClickHouseDB\Transport\StreamRead($stream); $r = $client->streamRead($streamRead, 'SELECT sin(number) as sin,cos(number) as cos FROM {table_name} LIMIT 4 FORMAT JSONEachRow', ['table_name'=>'system.numbers']);

会话管理

支持 ClickHouse 会话功能：

// 启用会话 $db->useSession(); $session_id = $db->getSession(); // 返回会话ID // 在会话中创建临时表 $db->write('CREATE TEMPORARY TABLE IF NOT EXISTS temp_session_test (number UInt64)'); // 重新连接到特定会话 $db->useSession($session_id);

性能优化建议

连接参数调优

合理配置连接参数可以显著提升性能：

$db->setTimeout(1.5); // 1.5秒超时 $db->setConnectTimeOut(5); // 5秒连接超时

查询设置优化

// 多种设置方式 $db->settings()->set('max_execution_time', 100); $db->settings()->apply([ 'max_execution_time' => 100, 'max_block_size' => 12345 ]);

错误处理与调试

异常处理机制

phpClickHouse 提供了完善的异常处理：

try { $db->ping(true); // 如果无法连接会抛出异常 } catch (Exception $e) { echo '连接异常：' . $e->getMessage(); }

调试功能

启用调试模式有助于排查问题：

$db->verbose(); // 启用详细日志 // 将调试信息输出到流 $stream = fopen('php://memory', 'r+'); $db->transport()->setStdErrOut($stream); // 执行查询后查看调试信息 $st = $db->select('SELECT 1 as ppp'); $st->rows(); rewind($stream); echo stream_get_contents($stream);

phpClickHouse 凭借其丰富的功能特性和优秀的性能表现，已经成为 PHP 开发者与 ClickHouse 数据库交互的首选工具。无论是简单的查询操作还是复杂的集群管理，该库都能提供完美的解决方案。

【免费下载链接】phpClickHousephp ClickHouse wrapper项目地址: https://gitcode.com/gh_mirrors/ph/phpClickHouse