PHPackages                             oralunal/phpclickhouse-laravel - 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. oralunal/phpclickhouse-laravel

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

oralunal/phpclickhouse-laravel
==============================

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

v1.2.0(1mo ago)0130MITPHPPHP ^8.5CI passing

Since Apr 9Pushed 1mo agoCompare

[ Source](https://github.com/oralunal/phpclickhouse-laravel)[ Packagist](https://packagist.org/packages/oralunal/phpclickhouse-laravel)[ Docs](https://github.com/oralunal/phpclickhouse-laravel)[ RSS](/packages/oralunal-phpclickhouse-laravel/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (3)Dependencies (7)Versions (4)Used By (0)

[![Tests](https://github.com/oralunal/phpclickhouse-laravel/actions/workflows/tests.yml/badge.svg)](https://github.com/oralunal/phpclickhouse-laravel/actions/workflows/tests.yml/badge.svg)[![Latest Version on Packagist](https://camo.githubusercontent.com/54da623268a8663d2d0f3da921a2931a89750705b107f2a94172d5f706d6675f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f72616c756e616c2f706870636c69636b686f7573652d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/oralunal/phpclickhouse-laravel)[![Total Downloads](https://camo.githubusercontent.com/71d6cdc7708bad8a1e7b7e7627996192c57f52132b86c892688298039e433a65/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f72616c756e616c2f706870636c69636b686f7573652d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/oralunal/phpclickhouse-laravel)

phpClickHouse-laravel
=====================

[](#phpclickhouse-laravel)

Laravel adapter for PHP ClickHouse tooling:

-  — HTTP transport and query execution
-  — fluent query builder (fork of `glushkovds/ClickhouseBuilder`, itself a fork of `the-tinderbox/ClickhouseBuilder`)

Features
--------

[](#features)

- Eloquent-flavored `BaseModel` (`create`, `save`, `insertBulk`, `insertAssoc`, `where`, pagination)
- `PhpClickHouseLaravel\Migration` base class for ClickHouse DDL migrations (single-node and cluster)
- Query builder integration with `settings()`, `chunk()`, and ClickHouse-specific grammar
- Column casts (currently `boolean`) applied on insert
- Model events: `creating`, `created`, `saved`
- Retry-on-network-error support (`retries` config key)
- Buffer engine support via `$tableForInserts` / `$tableSources`
- In-memory buffered inserts: accumulate rows with `Model::buffer()` and send them as a single HTTP request with `Model::flushBuffer()` (auto-flushed on script shutdown)
- `OPTIMIZE`, `TRUNCATE`, `ALTER TABLE ... DELETE`, `ALTER TABLE ... UPDATE` helpers
- Multi-instance and cluster-mode connections with active-node rotation
- Publishable default config — `.env` is enough for most setups

Underneath, smi2/phpClickHouse handles HTTP transport (curl-only, no PDO). More:

Prerequisites
-------------

[](#prerequisites)

- PHP 8.5+
- Laravel 13+
- ClickHouse server 24.x (older 20+ versions usually work but are no longer tested)

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

[](#installation)

**1.** Install via composer:

```
composer require oralunal/phpclickhouse-laravel
```

The service provider is registered automatically via Laravel package auto-discovery. If you have auto-discovery disabled, add `PhpClickHouseLaravel\ClickhouseServiceProvider::class` to `bootstrap/providers.php` (Laravel 11+) or `config/app.php` (Laravel 10 and below).

**2.** Configure the connection.

The simplest setup — just set these in your `.env`:

```
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=default
CLICKHOUSE_USERNAME=default
CLICKHOUSE_PASSWORD=
# only if you use an https connection
CLICKHOUSE_HTTPS=true
```

The service provider merges sensible defaults into `config('database.connections.clickhouse')` for you. No config edits needed for a single-node setup.

If you want to customize defaults beyond what env vars cover, publish the config:

```
php artisan vendor:publish --tag=clickhouse-config
```

That drops a `config/clickhouse.php` into your app. Alternatively, you can define the connection yourself in `config/database.php`:

```
'clickhouse' => [
    'driver' => 'clickhouse',
    'host' => env('CLICKHOUSE_HOST'),
    'port' => env('CLICKHOUSE_PORT', '8123'),
    'database' => env('CLICKHOUSE_DATABASE', 'default'),
    'username' => env('CLICKHOUSE_USERNAME', 'default'),
    'password' => env('CLICKHOUSE_PASSWORD', ''),
    'timeout_connect' => env('CLICKHOUSE_TIMEOUT_CONNECT', 2),
    'timeout_query' => env('CLICKHOUSE_TIMEOUT_QUERY', 2),
    'https' => (bool) env('CLICKHOUSE_HTTPS', null),
    'retries' => env('CLICKHOUSE_RETRIES', 0),
    'settings' => [ // optional
        'max_partitions_per_insert_block' => 300,
    ],
    'fix_default_query_builder' => true,
],
```

Usage
-----

[](#usage)

You can use smi2/phpClickHouse directly:

```
/** @var \ClickHouseDB\Client $db */
$db = DB::connection('clickhouse')->getClient();
$statement = $db->select('SELECT * FROM summing_url_views LIMIT 2');
```

More about `$db`:

#### Or use the Eloquent-like ORM

[](#or-use-the-eloquent-like-orm)

**1.** Add a model:

```