Laravel ClickHouse

A ClickHouse database driver for Laravel. Provides a familiar Eloquent Model, Query Builder, and Schema Builder with full support for ClickHouse-specific features.

Features

• Eloquent Model support with non-incrementing IDs
• Query Builder with ClickHouse extensions — ARRAY JOIN, FINAL clause, PREWHERE, SAMPLE, LIMIT BY, GLOBAL IN/NOT IN, ON CLUSTER, CTE (WITH), set operations (UNION/INTERSECT/EXCEPT DISTINCT), ClickHouse-specific joins (ANY, SEMI, ANTI, ASOF), empty/notEmpty checks, SETTINGS clause
• Schema Builder with ClickHouse DDL — ENGINE, PARTITION BY, ORDER BY, LowCardinality, Array types, index granularity
• Lightweight DELETE with partition targeting
• Parallel query execution via Guzzle async HTTP pool
• Two HTTP transports — Guzzle (default) and Curl (phpclickhouse)
• Laravel migrations with ClickHouse-compatible migration repository
• PHP 8.2+, Laravel 11+

Installation

composer require laravel-clickhouse/laravel-clickhouse

The package uses Laravel's auto-discovery — no manual service provider registration needed.

Add a ClickHouse connection to your config/database.php:

'connections' => [
    // ...

    'clickhouse' => [
        'driver'   => 'clickhouse',
        'host'     => env('CLICKHOUSE_HOST', '127.0.0.1'),
        'port'     => env('CLICKHOUSE_PORT', 8123),
        'database' => env('CLICKHOUSE_DATABASE', 'default'),
        'username' => env('CLICKHOUSE_USERNAME', 'default'),
        'password' => env('CLICKHOUSE_PASSWORD', ''),
        'https'    => env('CLICKHOUSE_HTTPS', false),
    ],
],

For full configuration options, see Installation & Configuration.

Quick Start

Query Builder

// Basic query with FINAL clause (merges data at query time)
$events = DB::connection('clickhouse')
    ->table('events', final: true)
    ->where('user_id', 1)
    ->get();

// ARRAY JOIN to expand array columns
$results = DB::connection('clickhouse')
    ->table('events')
    ->arrayJoin('tags', 'tag')
    ->where('tag', 'important')
    ->get();

// ClickHouse-specific join
$results = DB::connection('clickhouse')
    ->table('events')
    ->asofJoin('metrics', 'events.timestamp', 'metrics.timestamp')
    ->get();

Temporary Tables

ClickHouse temporary tables require all related HTTP requests to use the same session. Use session() to create a session for a group of queries:

$results = DB::connection('clickhouse')->session(function ($connection) {
    $connection->statement(
        'CREATE TEMPORARY TABLE tmp_words (word String) ENGINE = Memory'
    );

    $connection->table('tmp_words')->insert([
        'word' => 'clickhouse',
    ]);

    return $connection->table('tmp_words')->get();
}, timeout: 120);

The package generates a unique session ID and applies it to every query inside the callback. Once the callback finishes — including when it throws an exception — subsequent queries no longer join the session. The server keeps the session and its temporary tables alive until timeout seconds (60 by default) have passed since the session's last query; the timeout must not exceed the server's max_session_timeout setting (3600 by default).

ClickHouse executes at most one query per session at a time, so parallel queries (selectParallelly(), the Parallel helper) throw a LogicException when called inside session().

Eloquent Model

use ClickHouse\Laravel\Eloquent\Model;

class Event extends Model
{
    protected $connection = 'clickhouse';
    protected $table = 'events';
}

// Query as usual
$events = Event::where('user_id', 1)->get();

// Lightweight delete with partition
Event::where('user_id', 1)->delete(lightweight: true, partition: '202301');

Schema Builder

use ClickHouse\Laravel\Schema\Blueprint as ClickHouseBlueprint;

Schema::connection('clickhouse')->create('events', function (ClickHouseBlueprint $table) {
    $table->unsignedBigInteger('id');
    $table->string('name');
    $table->text('status')->lowCardinality();
    $table->array('tags', 'String');
    $table->dateTime('created_at');

    $table->engine('MergeTree()');
    $table->orderBy(['id', 'created_at']);
    $table->partitionBy('toYYYYMM(created_at)');
});

Parallel Queries

use ClickHouse\Laravel\Parallel;

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

// $results['users'] → Collection of User models
// $results['events'] → Collection of Event models

Documentation

Testing

composer test

Tests require a ClickHouse server running on 127.0.0.1:8123. See phpunit.xml.dist for configuration.

composer phpstan   # Static analysis
composer cs        # Code style check
composer cs:fix    # Fix code style

License

The MIT License (MIT). Please see License File for more information.