Laravel ClickHouse: A Full-Featured ClickHouse Driver for Laravel

Laravel ClickHouse is a database driver that integrates ClickHouse with Laravel, including Eloquent, the Query Builder, Schema Builder, and more:

• Eloquent models with non-incrementing ID support
• Query Builder with ClickHouse-specific clauses (i.e.,FINAL, ARRAY JOIN, SAMPLE)
• Schema Builder with ENGINE, PARTITION BY, ORDER BY, and LowCardinality column types
• Laravel migration support via artisan migrate
• Concurrent query execution using Guzzle’s async HTTP pool
• Dual HTTP transport options: Guzzle and Curl/phpclickhouse

ClickHouse is an open-source column-oriented database built for analytical workloads. It stores data by column rather than by row, making aggregations over large datasets fast—capable of querying billions of rows in seconds. It’s a common choice for event tracking, time-series data, and analytics dashboards where read performance at scale is the priority.

Eloquent Models

You can define Eloquent models pointing at ClickHouse the same way you would for any other database connection:

class Event extends Model
{
 protected $connection = 'clickhouse';
}
 
$events = Event::where('user_id', 1)->get();

ClickHouse doesn’t use auto-incrementing primary keys, so the driver configures models with non-incrementing IDs by default. Scopes and collections work as expected.

Query Builder with ClickHouse Extensions

The Query Builder covers standard Laravel methods and adds ClickHouse-specific clauses. The final parameter applies the FINAL modifier to a query, which forces ClickHouse to merge duplicate rows at read time—useful with the ReplacingMergeTree engine:

$events = DB::connection('clickhouse')
 ->table('events', final: true)
 ->where('user_id', 1)
 ->get();

Other extensions include PREWHERE (ClickHouse’s pre-filter for primary key columns), ARRAY JOIN, SAMPLE, LIMIT BY, and SEMI/ANTI/ASOF join types.

Schema Builder and Migrations

The Schema Builder supports ClickHouse DDL via a ClickHouseBlueprint, letting you define table engines, partition keys, order keys, and column types like LowCardinality:

Schema::connection('clickhouse')->create('events', function (ClickHouseBlueprint $table) {
 $table->engine('MergeTree()');
 $table->orderBy(['id', 'created_at']);
 $table->partitionBy('toYYYYMM(created_at)');
});

Standard artisan migrate commands work with a ClickHouse-compatible migration repository, so you can manage schema changes alongside your other databases.

Concurrent Query Execution

The package includes a Parallel helper that runs multiple queries at the same time using Guzzle’s async HTTP pool:

$results = Parallel::get([
 'users' => User::where('active', 1),
 'events' => Event::where('type', 'click'),
]);

Both users and events execute concurrently, and the results are returned as a keyed array once all queries resolve.

You can find the full documentation and source on GitHub.