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.