PHPackages                             timeleads/eloquent-clickhouse - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. timeleads/eloquent-clickhouse

ActiveLibrary[Database & ORM](/categories/database)

timeleads/eloquent-clickhouse
=============================

Laravel Eloquent driver for ClickHouse

1.2.2(1mo ago)081↑40%MITPHPPHP ^8.2CI passing

Since Sep 10Pushed 1mo agoCompare

[ Source](https://github.com/vaslv/eloquent-clickhouse)[ Packagist](https://packagist.org/packages/timeleads/eloquent-clickhouse)[ RSS](/packages/timeleads-eloquent-clickhouse/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (4)Versions (9)Used By (0)

Eloquent ClickHouse
===================

[](#eloquent-clickhouse)

**English** | [Русский](README.ru.md)

[![Laravel](https://camo.githubusercontent.com/9968736f39e4b95ff4a6c6a2e49141a56ffd5919aea3b65a9879d0175ac2dc93/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313225323025374325323031332d464632443230)](https://camo.githubusercontent.com/9968736f39e4b95ff4a6c6a2e49141a56ffd5919aea3b65a9879d0175ac2dc93/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313225323025374325323031332d464632443230)[![PHP](https://camo.githubusercontent.com/2795c86d2dea6aba6285347c2adef64310db832ec1d2d634a32e3b51115a5c95/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d373737424234)](https://camo.githubusercontent.com/2795c86d2dea6aba6285347c2adef64310db832ec1d2d634a32e3b51115a5c95/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d373737424234)[![CI](https://camo.githubusercontent.com/2237aeea48417693c11dc31144c0557c01f6a6d1c7f67031ac55f4b962970907/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f43492d636f6d7061746962696c697479253230636865636b732d324541343446)](https://camo.githubusercontent.com/2237aeea48417693c11dc31144c0557c01f6a6d1c7f67031ac55f4b962970907/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f43492d636f6d7061746962696c697479253230636865636b732d324541343446)

Laravel Eloquent driver for ClickHouse.

Compatibility
-------------

[](#compatibility)

PackageSupported versionsPHP8.2+Laravel / `illuminate/database`12.x, 13.xClickHouse client`smi2/phpclickhouse` 1.6+Compatibility is covered by automated checks (unit + live-ClickHouse integration tests) for:

- Laravel 12 on PHP 8.2 (lowest supported dependencies), 8.3 and 8.4
- Laravel 13 on PHP 8.3 and 8.4

See [.github/workflows/compatibility.yml](./.github/workflows/compatibility.yml).

Installation
------------

[](#installation)

```
composer require timeleads/eloquent-clickhouse
```

Configuration
-------------

[](#configuration)

Add a ClickHouse connection to `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', ''),
        'prefix' => '',
        'settings' => [
            // Server settings sent with every query, e.g.:
            // 'max_execution_time' => 60,
            // 'mutations_sync' => 1, // make update()/delete() wait for the mutation
        ],
        // Optional:
        // 'engine' => 'MergeTree',   // default table engine for migrations
        // 'timeout' => 30,           // query timeout, seconds (max_execution_time)
        // 'connect_timeout' => 5.0,  // connection timeout, seconds
    ],
],
```

Example `.env` values:

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

### TLS

[](#tls)

```
'clickhouse' => [
    // ...
    'port' => 8443,
    'https' => true,
    // 'sslCA' => '/path/to/ca.pem', // custom CA bundle ('ssl_ca' also accepted)
    // 'verify' => false,            // disable certificate verification (not recommended)
    // 'curl_options' => [CURLOPT_SSL_VERIFYHOST => 0], // raw overrides, win over the defaults
],
```

With `'https' => true` the server certificate is **verified by default** (the underlying smi2 client on its own disables verification). Note that the connector's initial `ping()`goes through an smi2 code path that never verifies certificates; all real queries do.

Usage
-----

[](#usage)

### Query Builder

[](#query-builder)

```
use Illuminate\Support\Facades\DB;

$rows = DB::connection('clickhouse')
    ->table('events')
    ->whereDate('created_at', now()->toDateString())
    ->get();
```

### Updates and deletes

[](#updates-and-deletes)

`update()` and `delete()` compile to ClickHouse mutations:

```
DB::connection('clickhouse')->table('events')->where('id', 1)->update(['name' => 'x']);
// ALTER TABLE "events" UPDATE "name" = 'x' WHERE "id" = 1

DB::connection('clickhouse')->table('events')->where('id', 1)->delete();
// ALTER TABLE "events" DELETE WHERE "id" = 1

DB::connection('clickhouse')->table('events')->delete(); // no WHERE
// TRUNCATE TABLE "events" — an unconditional delete truncates instead of mutating
```

Caveats inherent to ClickHouse:

- Mutations require a MergeTree-family engine. Log-family and Memory tables accept inserts and `truncate()`, but reject `update()`/`delete()`-with-`where`.
- Mutations are **asynchronous** by default: a read issued immediately after `update()`/`delete()` may see old data. Set `'settings' => ['mutations_sync' => 1]`to make them synchronous.
- The HTTP interface reports no affected-row count, so `update()`, `delete()`, `increment()` and `decrement()` always return `0`, and `updateOrInsert()` returns `false` on its update branch (the write itself succeeds).
- `insertGetId()` and `upsert()` throw: ClickHouse has no auto-increment, `RETURNING`or `ON CONFLICT`. Use explicit keys (e.g. UUIDs) and `insert()`; deduplicate with a `ReplacingMergeTree` engine where needed.

### Migrations

[](#migrations)

```
Schema::connection('clickhouse')->create('events', function (Blueprint $table) {
    $table->engine('MergeTree');          // default: MergeTree (or the 'engine' config)
    $table->uuid('id');
    $table->string('name')->default('');
    $table->dateTime('created_at', 3);
    $table->primary(['created_at', 'id']); // becomes ORDER BY (sorting key)
});
```

- The blueprint's `primary()` becomes the MergeTree `ORDER BY` sorting key; without one the table is created with `ORDER BY tuple()`. An engine string may carry its own clause: `$table->engine('MergeTree ORDER BY (id)')`.
- `hasTable()`, `hasColumn()`, `getTables()`, `getColumns()`, `getViews()`, `dropAllTables()` (and therefore `migrate:fresh`) work against `system.tables` / `system.columns`.
- Column types map to ClickHouse-native ones (`string` → `String`, `unsignedBigInteger` → `UInt64`, `dateTime($p)` → `DateTime64($p)`, `boolean` → `Bool`, `uuid` → `UUID`, `enum` → `Enum8`, ...). `nullable()` wraps the type in `Nullable(...)`.
- Unsupported concepts fail loudly with a `RuntimeException` instead of being silently skipped: auto-increment (`id()`/`increments()`), indexes, unique/foreign keys, `time()` columns, nullable columns inside the sorting key.

### Array and Map values

[](#array-and-map-values)

PHP arrays compile to ClickHouse-native literals: lists become `Array` literals, associative arrays become `Map` construction calls — in inserts, wheres, updates and raw bindings alike:

```
DB::connection('clickhouse')->table('events')->insert([
    'id' => 1,
    'tags' => ['alpha', 'beta'],          // -> ['alpha', 'beta']
    'attrs' => ['region' => 'eu'],        // -> map('region', 'eu')
]);

DB::connection('clickhouse')->table('events')->where('tags', ['alpha', 'beta'])->get();

DB::connection('clickhouse')->select('SELECT arrayConcat(?, ?) AS merged', [['a'], ['b']]);
```

### Raw statements

[](#raw-statements)

```
$rows = DB::connection('clickhouse')->select('SELECT * FROM events LIMIT 10');

DB::connection('clickhouse')->insert("INSERT INTO events (id, name) VALUES (1, 'test')");

DB::connection('clickhouse')->statement('OPTIMIZE TABLE events FINAL');
```

Notes
-----

[](#notes)

- The package registers the `clickhouse` database driver through its service provider.
- `select()` returns rows from `smi2/phpclickhouse` as associative arrays.
- Values are inlined into SQL with ClickHouse-safe escaping (the HTTP interface has no server-side prepared statements).
- Transactions are no-op methods because ClickHouse does not provide transactional behavior like traditional OLTP databases.

Development
-----------

[](#development)

A Docker test stack (PHP + live ClickHouse) is included:

```
make up               # start ClickHouse + PHP containers
make test             # unit tests
make test-integration # integration tests against the live ClickHouse
make test-all         # both
```

Run compatibility checks locally:

```
composer update
composer test
```

To verify the lowest supported Laravel 12 dependency set:

```
composer update --prefer-lowest
composer test
```

License
-------

[](#license)

MIT

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance90

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~38 days

Recently: every ~10 days

Total

8

Last Release

50d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/032ebe8f61d00ae1b569fd7f418e7f09825d093784070f7c2effd1c67d6fc3a0?d=identicon)[vaslv](/maintainers/vaslv)

---

Top Contributors

[![vaslv](https://avatars.githubusercontent.com/u/1648799?v=4)](https://github.com/vaslv "vaslv (7 commits)")

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/timeleads-eloquent-clickhouse/health.svg)

```
[![Health](https://phpackages.com/badges/timeleads-eloquent-clickhouse/health.svg)](https://phpackages.com/packages/timeleads-eloquent-clickhouse)
```

###  Alternatives

[glushkovds/phpclickhouse-laravel

Adapter of the most popular library https://github.com/smi2/phpClickHouse to Laravel

2051.5M2](/packages/glushkovds-phpclickhouse-laravel)[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k8.4M98](/packages/mongodb-laravel-mongodb)[kirschbaum-development/eloquent-power-joins

The Laravel magic applied to joins.

1.6k32.6M46](/packages/kirschbaum-development-eloquent-power-joins)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8793.2M25](/packages/yajra-laravel-oci8)[bavix/laravel-wallet

It's easy to work with a virtual wallet.

1.3k1.3M19](/packages/bavix-laravel-wallet)[laravel-liberu/laravel-gedcom

A package that converts gedcom files to Eloquent models

782.5k1](/packages/laravel-liberu-laravel-gedcom)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)