在现代 Web 应用开发中，数据量爆炸式增长已是常态。尤其是在日志分析、用户行为追踪、实时报表等场景下，我们常常需要对海量数据进行快速的聚合、过滤和统计。传统的行式关系型数据库，如 MySQL，虽然在事务处理和数据一致性方面表现出色，但在面对大数据量的复杂分析查询时，其性能瓶颈会很快显现。查询速度变慢，甚至导致应用响应迟钝，用户体验直线下降。
为了解决这个问题，许多开发者将目光投向了 ClickHouse——一个为在线分析处理（OLAP）而设计的开源列式数据库管理系统。ClickHouse 以其惊人的查询速度和数据压缩能力而闻名，是处理 PB 级数据的理想选择。然而，对于习惯了 Laravel 优雅开发模式的我们来说，如何将 ClickHouse 这头“猛兽”驯服，让它融入 Laravel 的生态，却是一个不小的挑战。
想象一下，你需要在 Laravel 应用中连接 ClickHouse，执行复杂的分析查询，甚至希望像操作 Eloquent 模型一样来操作 ClickHouse 表。如果没有一个合适的工具，你可能需要手动配置 ClickHouse 客户端，编写大量的原生 SQL 语句，并且无法享受到 Laravel 提供的数据库连接管理、查询构建器甚至迁移工具的便利。这不仅会增加开发成本，降低开发效率，还可能引入更多的错误。
好消息是，开源社区总是能为我们提供优雅的解决方案。
立即学习“PHP免费学习笔记（深入）”；
glushkovds/phpclickhouse-laravel
就是这样一个为 Laravel 和 Lumen 量身定制的 ClickHouse 适配器。它将最流行的 ClickHouse PHP 客户端
smi2/phpClickHouse
和强大的查询构建器
the-tinderbox/ClickhouseBuilder
完美地整合到 Laravel 框架中，让你能够在保持 Laravel 开发习惯的同时，轻松驾驭 ClickHouse 的强大性能。
如何使用 Composer 解决问题
使用
glushkovds/phpclickhouse-laravel
解决上述问题，步骤非常简单，一切都始于 Composer：
1. 安装依赖
首先，通过 Composer 将
glushkovds/phpclickhouse-laravel
包安装到你的 Laravel 项目中：
composer require glushkovds/phpclickhouse-laravel
这个包的依赖非常轻量，仅需要 PHP 8.0+ 和 Curl 扩展，无需其他复杂依赖。
2. 配置数据库连接
安装完成后，你需要像配置其他数据库连接一样，在
config/database.php
文件中添加 ClickHouse 的连接配置：
'clickhouse' => [
'driver' => 'clickhouse',
'host' => env('CLICKHOUSE_HOST'),
'port' => env('CLICKHOUSE_PORT', '8123'),
'database' => env('CLICKHOUSE_DATABASE', 'default'),
'username' => env('CLICKHOUSE_USERNAME', 'default'),
'password' => env('CLICKHOUSE_PASSWORD', ''),
'timeout_connect' => env('CLICKHOUSE_TIMEOUT_CONNECT', 2),
'timeout_query' => env('CLICKHOUSE_TIMEOUT_QUERY', 2),
'https' => (bool)env('CLICKHOUSE_HTTPS', null),
'retries' => env('CLICKHOUSE_RETRIES', 0),
'settings' => [ // 可选的 ClickHouse 服务器设置
'max_partitions_per_insert_block' => 300,
],
'fix_default_query_builder' => true,
],然后在你的
.env
文件中定义 ClickHouse 的连接信息：
CLICKHOUSE_HOST=localhost CLICKHOUSE_PORT=8123 CLICKHOUSE_DATABASE=default CLICKHOUSE_USERNAME=default CLICKHOUSE_PASSWORD= CLICKHOUSE_TIMEOUT_CONNECT=2 CLICKHOUSE_TIMEOUT_QUERY=2 # 如果使用 HTTPS 连接 # CLICKHOUSE_HTTPS=true
3. 注册服务提供者
最后一步，在
config/app.php
（或 Laravel 11+ 的
bootstrap/providers.php
）文件的
providers
数组中添加服务提供者。请注意，它应该放置在
App\Providers\AppServiceProvider::class
和
App\Providers\EventServiceProvider::class
之前，以确保其正确加载。
\PhpClickHouseLaravel\ClickhouseServiceProvider::class,
至此，你的 Laravel 应用已经成功连接到 ClickHouse 数据库了！
享受 Laravel 式的 ClickHouse 操作体验
glushkovds/phpclickhouse-laravel
最令人兴奋的莫过于它提供了接近 Eloquent ORM 的操作体验，让你可以用熟悉的方式与 ClickHouse 交互。
直接获取 ClickHouse 客户端
如果你需要直接使用底层
smi2/phpClickHouse
客户端的功能，可以这样获取：
use Illuminate\Support\Facades\DB;
use ClickHouseDB\Client;
/** @var Client $db */
$db = DB::connection('clickhouse')->getClient();
$statement = $db->select('SELECT * FROM my_table LIMIT 2');
// ... 更多底层操作Eloquent-like 模型操作
这才是真正的“杀手锏”！你可以创建 ClickHouse 模型，并像操作 Eloquent 模型一样进行数据插入、查询等操作。
-
定义 ClickHouse 模型
创建一个继承自
PhpClickHouseLaravel\BaseModel
的模型：<?php namespace App\Models\Clickhouse; use PhpClickHouseLaravel\BaseModel; class MyTable extends BaseModel { // 默认情况下，表名会从类名推断（MyTable => my_table）， // 如果不一致，可以显式指定 protected $table = 'my_table'; // 还可以定义类型转换，例如布尔值 protected $casts = ['is_active' => 'boolean']; } -
创建 ClickHouse 迁移
你甚至可以使用熟悉的 Laravel 迁移来管理 ClickHouse 的表结构，这极大地简化了数据库版本控制的工作：
<?php use PhpClickHouseLaravel\Migration; use Illuminate\Database\Schema\Blueprint; use Illuminate\Support\Facades\Schema; return new class extends Migration { public function up(): void { static::write(' CREATE TABLE my_table ( id UInt32, created_at DateTime, field_one String, field_two Int32 ) ENGINE = MergeTree() ORDER BY (id) '); } public function down(): void { static::write('DROP TABLE my_table'); } }; -
插入数据
支持单行插入和批量插入：
use App\Models\Clickhouse\MyTable; // 单行插入 MyTable::create(['field_one' => 'model 1', 'field_two' => 123]); // 批量关联数组插入 MyTable::insertAssoc([ ['field_one' => 'model A', 'field_two' => 10], ['field_one' => 'model B', 'field_two' => 20], ]); // 批量非关联数组插入（需指定字段顺序） MyTable::insertBulk([['model C', 30], ['model D', 40]], ['field_one', 'field_two']); -
查询数据
使用类似 Laravel 查询构建器的方式进行查询：
use App\Models\Clickhouse\MyTable; use PhpClickHouseLaravel\RawColumn; $rows = MyTable::select(['field_one', new RawColumn('sum(field_two)', 'total_field_two')]) ->where('created_at', '>', '2023-01-01 00:00:00') ->groupBy('field_one') ->settings(['max_threads' => 3]) // 可选的 ClickHouse 查询设置 ->getRows(); foreach ($rows as $row) { echo "Field One: {$row['field_one']}, Total Field Two: {$row['total_field_two']}\n"; }
更多高级功能
该库还支持许多高级特性，进一步提升开发效率和应用性能：
-
事件 (Events)：支持
creating
,created
,saved
等事件，与 Eloquent 模型事件类似。 - 重试机制 (Retries)：当网络连接不稳定时，可以配置请求重试次数。
- 数据分块 (Chunking)：处理大量查询结果时，可以像 Laravel 那样分块处理，避免内存溢出。
-
Buffer 引擎支持：可以通过配置
protected $tableForInserts
来实现数据写入到 ClickHouse 的 Buffer 表，提高写入吞吐量。 -
DML 操作：支持
OPTIMIZE
、TRUNCATE
、DELETE
和UPDATE
等 ClickHouse 特有的数据操作语句。 - 多实例与集群模式：支持配置多个 ClickHouse 连接，甚至可以配置 ClickHouse 集群，实现高可用和负载均衡。
总结与展望
glushkovds/phpclickhouse-laravel
极大地简化了 Laravel 应用与 ClickHouse 数据库的集成过程。它让开发者能够：
- 无缝集成：告别繁琐的底层 API 调用，拥抱 Laravel 的优雅开发体验。
- 性能飞跃：充分利用 ClickHouse 在大数据分析方面的极致性能，让你的报表和分析功能快如闪电。
- 维护便捷：通过 Laravel 迁移管理 ClickHouse 表结构，以及 Eloquent-like 的模型操作，提高了代码的可读性和可维护性。
- 功能全面：从基础的增删改查到高级的集群支持、DML 操作，满足了各种复杂场景的需求。
如果你正在寻找一个在 Laravel 项目中高效处理海量数据分析的方案，并且希望能够保持原有的开发习惯，那么
glushkovds/phpclickhouse-laravel
绝对值得一试。它将是你应对大数据挑战的得力助手，让你的 Laravel 应用在数据分析的道路上更加游刃有余。
