ariadata/laravel-clickhouse

ClickHouse database driver for Laravel — Eloquent, query builder, and schema support (Laravel 13+).

1.0.0 2026-04-04 11:15 UTC

Requires

• php: ^8.3
• illuminate/database: ^13.0
• illuminate/support: ^13.0
• smi2/phpclickhouse: ^1.6

Requires (Dev)

• mockery/mockery: ^1.6
• orchestra/testbench: ^11.0
• phpunit/phpunit: ^11.5.50|^12.5.8

MIT

• Ariadata
• Kundan

• database
• analytics
• laravel
• olap
• eloquent
• big-data
• clickhouse

README

ariadata/laravel-clickhouse — a Laravel database driver for ClickHouse with Eloquent, the query builder, schema tooling, and ClickHouse-specific query helpers.

Forked and maintained from kundan-in/clickhouse-laravel with a new vendor namespace: Ariadata\LaravelClickHouse.

Requirements

• PHP 8.3+
• Laravel 13.x
• ClickHouse server (HTTP interface, default port 8123)

Installation

composer require ariadata/laravel-clickhouse

Laravel will auto-discover ClickHouseServiceProvider and register the ClickHouse facade.

Configuration

1. Publish config (optional)

php artisan vendor:publish --provider="Ariadata\LaravelClickHouse\ClickHouseServiceProvider" --tag="clickhouse-config"

2. Environment

CLICKHOUSE_HOST=127.0.0.1
CLICKHOUSE_PORT=8123
CLICKHOUSE_USERNAME=default
CLICKHOUSE_PASSWORD=
CLICKHOUSE_DATABASE=default

3. config/database.php

'connections' => [
    // ...

    'clickhouse' => [
        'driver' => 'clickhouse',
        'host' => env('CLICKHOUSE_HOST', '127.0.0.1'),
        'port' => env('CLICKHOUSE_PORT', 8123),
        'username' => env('CLICKHOUSE_USERNAME', 'default'),
        'password' => env('CLICKHOUSE_PASSWORD', ''),
        'database' => env('CLICKHOUSE_DATABASE', 'default'),
        'settings' => [
            'readonly' => env('CLICKHOUSE_READONLY', 0),
            'max_execution_time' => env('CLICKHOUSE_MAX_EXECUTION_TIME', 60),
        ],
    ],
],

Usage

Eloquent model

<?php

namespace App\Models;

use Ariadata\LaravelClickHouse\Database\ClickHouseModel;

class AnalyticsEvent extends ClickHouseModel
{
    protected $connection = 'clickhouse';

    protected $table = 'analytics_events';

    public $timestamps = false;

    protected function casts(): array
    {
        return [
            'properties' => \Ariadata\LaravelClickHouse\Casts\ClickHouseJson::class,
            'tags' => \Ariadata\LaravelClickHouse\Casts\ClickHouseArray::class,
        ];
    }
}

Facade

use Ariadata\LaravelClickHouse\Facades\ClickHouse;

$rows = ClickHouse::select('SELECT * FROM analytics_events WHERE user_id = ?', [1]);

ClickHouse::healthCheck();
ClickHouse::getServerVersion();

ClickHouse::table('analytics_events')
    ->where('created_at', '>=', today())
    ->get();

Schema (ClickHouse engines, MergeTree, etc.)

Use Schema::connection('clickhouse') with the package’s blueprint helpers — see SPEC.md and tests for examples.

Migrating from kundan-in/clickhouse-laravel

1. Replace the Composer package with ariadata/laravel-clickhouse.
2. Find/replace namespace KundanIn\ClickHouseLaravel → Ariadata\LaravelClickHouse in your app (models, facades, casts, imports).
3. Republish config if you reference the old provider name in docs/scripts.

Development

composer install
composer test

License

MIT. See LICENSE. Includes copyright of the original author; see CHANGELOG.md.

Contributing

Issues and pull requests are welcome in this repository’s GitHub project.