phpClickHouse Laravel

https://github.com/glushkovds/phpclickhouse-laravel
Admin
A Laravel and Lumen adapter for ClickHouse that provides database connections, query building, and...
Tokens:58,847
Snippets:467
Trust Score:7.4
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Run this command to install the package via Composer.

```sh
$ composer require glushkovds/phpclickhouse-laravel
```

--------------------------------

### Cluster mode migration example

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Example of a migration script for a cluster environment using ReplicatedMergeTree.

```php
<?php

return new class extends \PhpClickHouseLaravel\Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        static::write('
            CREATE TABLE my_table (
                id UInt32,
                created_at DateTime,
                field_one String,
                field_two Int32
            )
            ENGINE = ReplicatedMergeTree('/clickhouse/tables/default.my_table', '{replica}')
            ORDER BY (id)
        ');
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        static::write('DROP TABLE my_table');
    }
};
```

--------------------------------

### Connecting and sliding nodes example

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to get the current node host and slide to the next node. Output comments show expected host values.

```php
$row = new MyTable();
echo $row->getThisClient()->getConnectHost();
// 'clickhouse01'

$row->resolveConnection()->getCluster()->slideNode();
echo $row->getThisClient()->getConnectHost();
// 'clickhouse02'
```

--------------------------------

### Usage example for getClient()

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to retrieve the ClickHouseDB\Client instance via the connection.

```php
$db = DB::connection('clickhouse')->getClient();
```

--------------------------------

### Manual registration in Lumen bootstrap file

Source: https://github.com/glushkovds/phpclickhouse-laravel

Example of registering the provider manually in a Lumen bootstrap file.

```php
// bootstrap/app.php or app.php
$app->register(\PhpClickHouseLaravel\ClickhouseServiceProvider::class);
```

--------------------------------

### Direct usage example

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to instantiate and configure the curler directly, setting retries to 2 for up to 3 total attempts.

```php
use PhpClickHouseLaravel\CurlerRollingWithRetries;

$curler = new CurlerRollingWithRetries();
$curler->setRetries(2);          // up to 3 total attempts
echo $curler->getRetries();      // 2
```

--------------------------------

### Model-based select with settings, chunking and pagination

Source: https://github.com/glushkovds/phpclickhouse-laravel

Example of a select query with raw column, where clause, group by, settings, and getRows.

```php
$rows = MyTable::select(['field_one', new RawColumn('sum(field_two)', 'field_two_sum')])
    ->where('created_at', '>', '2020-09-14 12:47:29')
    ->groupBy('field_one')
    ->settings(['max_threads' => 3])
    ->getRows();
```

--------------------------------

### Plain SQL migration example

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows a basic migration class using static::write() with raw SQL to create and drop a table. The up() method creates a MergeTree table with specified columns and order by, down() drops it.

```php
<?php

class CreateMyTable extends \PhpClickHouseLaravel\Migration
{
    public function up()
    {
        static::write('
            CREATE TABLE my_table (
                id UInt32,
                created_at DateTime,
                field_one String,
                field_two Int32
            )
            ENGINE = MergeTree()
            ORDER BY (id)
        ');
    }

    public function down()
    {
        static::write('DROP TABLE my_table');
    }
}
```

--------------------------------

### Paginate with Laravel's paginator

Source: https://github.com/glushkovds/phpclickhouse-laravel

Example of paginating a query and iterating over items, then echoing pagination links.

```php
$paginator = MyTable::select(['field_one', 'field_two'])
    ->where('created_at', '>', '2020-09-14 12:47:29')
    ->paginate(perPage: 30, pageName: 'page');

foreach ($paginator->items() as $row) {
    echo $row['field_one'];
}
echo $paginator->links();
```

--------------------------------

### Map usage example

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to use Map in an insertAssoc call to insert a map into a ClickHouse Map column.

```php
MyTable::insertAssoc([[1, 'str', new Map(['a' => 'b', 'c' => 'd'])]]);
```

--------------------------------

### Read from buffer table by setting $table

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

If you also want to read from the buffer table, set $table to the buffer table name. This example shows a model with $table set to 'my_table_buffer'.

```php
<?php

namespace App\Models\Clickhouse;

use PhpClickHouseLaravel\BaseModel;

class MyTable extends BaseModel
{
    protected $table = 'my_table_buffer';
}
```

--------------------------------

### get(array $bindings = []): Statement

Source: https://github.com/glushkovds/phpclickhouse-laravel

Compiles the query to SQL, executes it via the client, logs the query, and returns a LaravelStatement. Note that this differs from Laravel's Collection-returning get() — call ->rows() for arrays or ->all() for objects.

```APIDOC
## get(array $bindings = []): Statement

### Description
Compiles the query to SQL, executes it via the client, logs the query, and returns a LaravelStatement. Note that this differs from Laravel's Collection-returning get() — call ->rows() for arrays or ->all() for objects.

### Method
get

### Parameters
#### Request Body
- **$bindings** (array) - Optional - Query bindings. Default: `[]`.

### Response
#### Success Response
- **Statement** - A `LaravelStatement` (a `ClickHouseDB\Statement` subclass).

### Source
`src/Builder.php:74`
```

--------------------------------

### Chunk results with chunk()

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Chunk query results into batches of a specified size, similar to Laravel's chunk method. The example splits results into chunks of 30 rows and iterates over each row.

```php
// Split the result into chunks of 30 rows.
$rows = MyTable::select(['field_one', 'field_two'])
    ->chunk(30, function ($rows) {
        foreach ($rows as $row) {
            echo $row['field_two'] . "\n";
        }
    });
```

--------------------------------

### Statement rows as objects example

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to retrieve rows as objects using all(), matching Laravel query-builder shape. Access fields with object syntax.

```php
$objects = MyTable::where('field_one', 123)->get()->all();

foreach ($objects as $row) {
    echo $row->field_one;
}
```

--------------------------------

### Cluster mode database connection configuration

Source: https://github.com/glushkovds/phpclickhouse-laravel

Defines a ClickHouse connection in config/database.php with cluster settings, including multiple hosts, timeouts, HTTPS, retries, and custom settings. Use this as a full example for cluster mode with settings.

```php
// config/database.php
'connections' => [
    'clickhouse' => [
        'driver' => 'clickhouse',
        'cluster' => [
            ['host' => 'clickhouse01', 'port' => 8123],
            ['host' => 'clickhouse02', 'port' => 8123],
        ],
        'database' => env('CLICKHOUSE_DATABASE', 'default'),
        'username' => env('CLICKHOUSE_USERNAME', 'default'),
        'password' => env('CLICKHOUSE_PASSWORD', ''),
        'timeout_connect' => (int) env('CLICKHOUSE_TIMEOUT_CONNECT', 2),
        'timeout_query' => (int) env('CLICKHOUSE_TIMEOUT_QUERY', 2),
        'https' => (bool) env('CLICKHOUSE_HTTPS', false),
        'retries' => (int) env('CLICKHOUSE_RETRIES', 0),
        'settings' => ['max_partitions_per_insert_block' => 300],
        'cluster_name' => 'company_cluster',
        'fix_default_query_builder' => true,
    ],
],

```

--------------------------------

### getElapsedTime method signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Protected method that returns elapsed milliseconds since a start time, calculated as round((microtime(true) - $start) * 1000, 2).

```php
protected function getElapsedTime($start)
```

--------------------------------

### Buffer engine for insert queries

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Define a model with $tableForInserts to route inserts to a buffer table while selects use $table. The example shows a model with $table set to 'my_table' and $tableForInserts set to 'my_table_buffer'.

```php
<?php

namespace App\Models\Clickhouse;

use PhpClickHouseLaravel\BaseModel;

class MyTable extends BaseModel
{
    // Optional. By default, MyTable resolves to my_table.
    protected $table = 'my_table';

    // Inserts use $tableForInserts, selects use $table.
    protected $tableForInserts = 'my_table_buffer';
}
```

--------------------------------

### Configuring retries via clickhouse connection

Source: https://github.com/glushkovds/phpclickhouse-laravel

Example configuration in config/database.php to enable retries via the CLICKHOUSE_RETRIES environment variable.

```php
// config/database.php
'clickhouse' => [
    'driver' => 'clickhouse',
    'host' => env('CLICKHOUSE_HOST'),
    'retries' => (int) env('CLICKHOUSE_RETRIES', 0),
    // ...
],
```

--------------------------------

### InsertArray usage example

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to use InsertArray in an insertAssoc call to insert an array into a ClickHouse Array column.

```php
MyTable::insertAssoc([[1, 'str', new InsertArray(['a', 'b'])]]);
```

--------------------------------

### Statement rows as arrays example

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to retrieve rows as arrays using the default ClickHouse shape via rows(). Iterates and accesses fields with array syntax.

```php
$statement = MyTable::where('field_one', 123)->get();
$rows = $statement->rows();

foreach ($rows as $row) {
    echo $row['field_one'];
}
```

--------------------------------

### RawColumn usage examples

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows RawColumn used in select, update with raw expression, and update with date arithmetic. The raw SQL fragment is inserted verbatim.

```php
$rows = MyTable::select(['field_one', new RawColumn('sum(field_two)', 'field_two_sum')])
    ->groupBy('field_one')
    ->getRows();

// UPDATE with raw expression
MyTable::where('field_one', 123)
    ->update(['field_two' => new RawColumn("concat(field_two,'new_val')")]);

// UPDATE with date arithmetic
MyTable::where('field_one', 123)->update([
    'created_at' => new RawColumn('created_at + INTERVAL 1 YEAR'),
]);
```

--------------------------------

### resolveConnection(): Connection

Source: https://github.com/glushkovds/phpclickhouse-laravel

Returns DB::connection($this->connection) as a PhpClickHouseLaravel\Connection. Used in README cluster examples and by Migration::write() and Builder::get().

```php
public function resolveConnection(): Connection
```

--------------------------------

### getClient(): Client (static, deprecated)

Source: https://github.com/glushkovds/phpclickhouse-laravel

Static variant returning the client via DB::connection((new static())->connection)->getClient(). Deprecated; use getThisClient() instead. Still used in README examples.

```php
/**
 * @return Client
 * @deprecated use $this->getThisClient() instead
 */
public static function getClient(): Client
```

--------------------------------

### getClient(): Client (static, deprecated)

Source: https://github.com/glushkovds/phpclickhouse-laravel

Static variant that returns the ClickHouseDB\Client for the connection. Deprecated; use getThisClient() instead. Still widely used in README examples.

```APIDOC
## getClient(): Client (static, deprecated)

### Description
Static variant that returns the `ClickHouseDB\Client` for the connection. Deprecated; use `getThisClient()` instead.

### Method
Static method

### Signature
```php
/**
 * @return Client
 * @deprecated use $this->getThisClient() instead
 */
public static function getClient(): Client
```

### Returns
- **Client** - The `ClickHouseDB\Client` for the connection.

### Usage
```php
MyTable::getClient()->write('ALTER TABLE ...');
MyTable::getClient()->getConnectHost();
```
```

--------------------------------

### Register event listener for ClickHouse model

Source: https://github.com/glushkovds/phpclickhouse-laravel

Listeners register against 'eloquent.{event}: ' . static::class. This example registers a listener for the 'creating' event on App\Models\Clickhouse\MyTable. The callback receives the model instance.

```php
use Illuminate\Support\Facades\Event;

Event::listen('eloquent.creating: App\Models\Clickhouse\MyTable', function ($model) {
    // validate
});
```

--------------------------------

### Using the connection after boot

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to use the connection through the DB facade after the provider boots.

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

$db = DB::connection('clickhouse')->getClient();
$statement = $db->select('SELECT * FROM my_table LIMIT 2');
```

--------------------------------

### boot() method signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Public method that registers the connection resolver and sets the event dispatcher.

```php
public function boot(): void
```

--------------------------------

### Breaking change: update DB::table()->get() usage

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/docs/known_issues.md

Existing code using DB::table('my-table')->get() returns a Collection. After the fix, it returns a Statement, so you must call ->rows() to get an array.

```php
$rows = DB::table('my-table')
    ...
    ->get(); // Collection
```

```php
$rows = DB::table('my-table')
    ...
    ->get() // Statement
    ->rows(); // array
```

--------------------------------

### Package config file (config/clickhouse.php)

Source: https://github.com/glushkovds/phpclickhouse-laravel

Returns the default connection configuration array for the Clickhouse driver. Reads environment variables with defaults, and conditionally adds the 'max_partitions_per_insert_block' setting from CLICKHOUSE_MAX_PARTITIONS_PER_INSERT_BLOCK. This file is merged into config key 'clickhouse' by ClickhouseServiceProvider::register().

```php
<?php

$settings = [];
if (!is_null($maxPartitionsSetting = env('CLICKHOUSE_MAX_PARTITIONS_PER_INSERT_BLOCK'))) {
    $settings['max_partitions_per_insert_block'] = (int)$maxPartitionsSetting;
}

return [
    'connection' => [
        'driver' => 'clickhouse',
        'host' => env('CLICKHOUSE_HOST', 'localhost'),
        'port' => (int)env('CLICKHOUSE_PORT', 8123),
        'database' => env('CLICKHOUSE_DATABASE', 'default'),
        'username' => env('CLICKHOUSE_USERNAME', 'default'),
        'password' => env('CLICKHOUSE_PASSWORD', ''),
        'timeout_connect' => (int)env('CLICKHOUSE_TIMEOUT_CONNECT', 2),
        'timeout_query' => (int)env('CLICKHOUSE_TIMEOUT_QUERY', 2),
        'https' => (bool)env('CLICKHOUSE_HTTPS', false),
        'retries' => (int)env('CLICKHOUSE_RETRIES', 0),
        'settings' => $settings,
        'fix_default_query_builder' => (bool)env('CLICKHOUSE_FIX_DEFAULT_QUERY_BUILDER', true),
    ],
];
```

--------------------------------

### Configure ClickHouse Cluster mode

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Set up the cluster configuration in config/database.php. Ensure all nodes share the same database credentials.

```php
'clickhouse' => [
    'driver' => 'clickhouse',
    'cluster' => [
        [
            'host' => 'clickhouse01',
            'port' => 8123,
        ],
        [
            'host' => 'clickhouse02',
            '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,
],
```

--------------------------------

### Insert array data type with InsertArray

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Use InsertArray to insert array data types. The example inserts a row with an array value.

```php
// Array data type
MyTable::insertAssoc([[1, 'str', new InsertArray(['a','b'])]]);
```

--------------------------------

### run() protected method signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Custom run that fires beforeExecutingCallbacks, times the closure, logs the query, and returns the closure result.

```php
protected function run($query, $bindings, Closure $callback)
```

--------------------------------

### Lightweight update with updateLightweight()

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Use updateLightweight() for point updates that write a patch instead of rewriting parts. Requires ClickHouse >= 25.x and the target table must have the settings enabled as shown in the previous snippet.

```php
MyTable::where('field_one', 123)->updateLightweight(['field_two' => 'new_val']);
```

--------------------------------

### Create Migration for secondary connection

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Define a migration class that targets the secondary connection.

```php
<?php

return new class extends \PhpClickHouseLaravel\Migration
{
    protected $connection = 'clickhouse2';
    
    public function up()
    {
        static::write('CREATE TABLE my_table2 ...');
    }
    
    public function down()
    {
        static::write('DROP TABLE my_table2');
    }
};
```

--------------------------------

### resolveConnection(): Connection

Source: https://github.com/glushkovds/phpclickhouse-laravel

Returns the Laravel connection as a PhpClickHouseLaravel\Connection. Used in README cluster examples and by Migration::write() and Builder::get().

```APIDOC
## resolveConnection(): Connection

### Description
Returns the Laravel connection as a `PhpClickHouseLaravel\Connection`.

### Method
Instance method

### Signature
```php
public function resolveConnection(): Connection
```

### Returns
- **Connection** - The `PhpClickHouseLaravel\Connection` for the connection.

### Usage
```php
$row->resolveConnection()->getCluster()->slideNode();
```
```

--------------------------------

### Creating Migrations with Schema Builder

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Use the fluent Schema Builder to define table columns and settings instead of writing raw SQL.

```php
<?php

class CreateMyTable extends \PhpClickHouseLaravel\Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        static::createMergeTree('my_table', fn(MergeTree $table) => $table
            ->columns([
                $table->uInt32('id'),
                $table->datetime('created_at', 3)->default(new Expression('now64()')),
                $table->string('field_one'),
                $table->int32('field_two'),
            ])
            ->orderBy('id')
        );
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        static::write('DROP TABLE my_table');
    }
}
```

--------------------------------

### query() implementation

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows the conditional logic for returning the custom builder or the default one.

```php
if ($this->config['fix_default_query_builder'] ?? false) {
    return new Builder();
}
return parent::query();
```

--------------------------------

### createWithClient static factory method

Source: https://github.com/glushkovds/phpclickhouse-laravel

Static factory method that constructs the connection and builds a Cluster from the config. Used by the clickhouse driver resolver. Requires an array config with 'database' and optional 'cluster' keys.

```php
/**
 * @param array $config
 * @return static
 */
public static function createWithClient(array $config): self
```

--------------------------------

### getSettings(): array

Source: https://github.com/glushkovds/phpclickhouse-laravel

Returns the current settings array stored in the builder. This method is also consulted by updateLightweight().

```APIDOC
## getSettings(): array

### Description
Returns the current settings array stored in the builder. This method is also consulted by updateLightweight().

### Method
getSettings

### Response
#### Success Response
- **array** - The current settings array.

### Source
`src/Builder.php:55`
```

--------------------------------

### getRows(array $bindings = []): array

Source: https://github.com/glushkovds/phpclickhouse-laravel

Executes the query and returns the result rows as an array of associative arrays. This method is a convenience wrapper around get() and rows().

```APIDOC
## getRows(array $bindings = []): array

### Description
Returns the result rows as an array of associative arrays.

### Method
PHP method

### Signature
```php
public function getRows(array $bindings = []): array
```

### Parameters
- **$bindings** (array) - Optional - Query bindings.

### Return Value
- **array** - The result rows as an array of associative arrays.
```

--------------------------------

### register() method signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Public method that merges config and registers default connection config.

```php
public function register(): void
```

--------------------------------

### useWritePdo()

Source: https://github.com/glushkovds/phpclickhouse-laravel

Compatibility no-op that returns the builder instance. Provided for Laravel compatibility.

```APIDOC
## useWritePdo()

### Description
Compatibility no-op that returns the builder instance. Provided for Laravel compatibility.

### Method
useWritePdo

### Response
Returns `$this`.
```

--------------------------------

### select() method signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Runs a SELECT query through the active node. The SQL is rewritten by QueryGrammar::prepareParameters() to replace #@? with numbered placeholders. Returns an array of result rows.

```php
public function select($query, $bindings = [], $useReadPdo = true, array $fetchUsing = []): array
```

--------------------------------

### Switching nodes in cluster mode

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Retrieve the current node host and manually switch to the next available node in the cluster.

```php
$row = new MyTable();
echo $row->getThisClient()->getConnectHost();
// will print 'clickhouse01'
$row->resolveConnection()->getCluster()->slideNode();
echo $row->getThisClient()->getConnectHost();
// will print 'clickhouse02'
```

--------------------------------

### Register ClickhouseServiceProvider manually in Lumen

Source: https://github.com/glushkovds/phpclickhouse-laravel

Use this when package discovery is disabled or in Lumen. Place in bootstrap/app.php or app.php.

```php
$app->register(\PhpClickHouseLaravel\ClickhouseServiceProvider::class);
```

--------------------------------

### Update, lightweight update, delete with error handling

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows update and updateLightweight calls with try-catch for QueryException, and a delete call.

```php
use PhpClickHouseLaravel\Exceptions\QueryException;

try {
    MyTable::where('field_one', 123)->update(['field_two' => 'new_val']);
    MyTable::where('field_one', 123)->updateLightweight(['field_two' => 'new_val']);
} catch (QueryException $e) {
    if ($e->getMessage() === 'Error updating empty values') {
        // update()/updateLightweight() called with an empty $values array
    }
}

MyTable::where('field_one', 123)->delete();
```

--------------------------------

### newQuery(): self

Source: https://github.com/glushkovds/phpclickhouse-laravel

Creates a new builder instance sharing the same client. Used internally by count() and cloning helpers.

```APIDOC
## newQuery(): self

### Description
Returns a fresh builder sharing the same client.

### Method
newQuery

### Signature
```php
public function newQuery(): self
```

### Returns
- **self** - A new builder instance with the same client.
```

--------------------------------

### LaravelStatement::all(): array

Source: https://github.com/glushkovds/phpclickhouse-laravel

Returns the result rows as an array of objects, matching the shape Laravel's query builder returns from get(). Each row is converted from an associative array to a plain object.

```APIDOC
## [METHOD] LaravelStatement::all(): array

### Description
Returns the result rows as an array of objects, matching the shape Laravel's query builder returns from get(). Each row is converted from an associative array to a plain object.

### Method
Instance method

### Signature
```php
public function all(): array
```

### Return Value
- `array` - Array of objects, each representing a row.

### Example
```php
$objects = MyTable::where('field_one', 123)->get()->all();

foreach ($objects as $row) {
    echo $row->field_one;
}
```
```

--------------------------------

### write method signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Protected static method to execute SQL on every cluster node. Accepts SQL and optional bindings, returns Statement.

```php
/**
 * @param string $sql
 * @param array $bindings
 * @return Statement
 */
protected static function write(string $sql, array $bindings = []): Statement
```

--------------------------------

### Error inspection after insert example

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows error inspection after a write-style statement. Note that insert family returns raw ClickHouseDB\Statement, not LaravelStatement. Uses isError() and getRequest()->getResponseError() to surface transport/HTTP errors.

```php
$statement = MyTable::insertAssoc([['model_name' => 'model 1', 'some_param' => 1]]);
if ($statement->isError()) {
    // surface the underlying transport/HTTP error
    report($statement->getRequest()->getResponseError() ?? 'insert failed');
}
```

--------------------------------

### Creating Migrations with Raw SQL

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Define table structures using raw SQL within the up and down methods of a migration class extending \PhpClickHouseLaravel\Migration.

```php
<?php

class CreateMyTable extends \PhpClickHouseLaravel\Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        static::write('
            CREATE TABLE my_table (
                id UInt32,
                created_at DateTime,
                field_one String,
                field_two Int32
            )
            ENGINE = MergeTree()
            ORDER BY (id)
        ');
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        static::write('DROP TABLE my_table');
    }
}
```

--------------------------------

### Column casting with $casts property

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Define a model with a $casts property to convert columns to boolean before insertion. This feature does not apply to data selection. Supported cast types: boolean. The example shows a model class and a subsequent insert call.

```php
namespace App\Models\Clickhouse;

use PhpClickHouseLaravel\BaseModel;

class MyTable extends BaseModel
{
    /**
     * The columns that should be cast.
     *
     * @var array
     */
    protected $casts = ['some_bool_column' => 'boolean'];
}
// Then you can insert the data like this:
MyTable::insertAssoc([
    ['some_param' => 1, 'some_bool_column' => false],
]);
```

--------------------------------

### Define Model for secondary connection

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Create a model that specifies the secondary connection by setting the $connection property.

```php
<?php

namespace App\Models\Clickhouse;

use PhpClickHouseLaravel\BaseModel;

class MyTable2 extends BaseModel
{
    protected $connection = 'clickhouse2';
    
    protected $table = 'my_table2';
}
```

--------------------------------

### BaseModel class declaration with traits

Source: https://github.com/glushkovds/phpclickhouse-laravel

Defines the BaseModel class using HasAttributes, HidesAttributes, HasEvents, and WithClient traits. Extend this class to get ClickHouse model methods like create, select, where, update, optimize, and truncate.

```php
class BaseModel
{
    use HasAttributes;
    use HidesAttributes;
    use HasEvents;
    use WithClient;
}
```

--------------------------------

### OPTIMIZE statement

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Run the OPTIMIZE statement on a table. The method accepts optional $final and $partition parameters.

```php
MyTable::optimize($final = false, $partition = null);
```

--------------------------------

### Catch Exception from BaseModel::save()

Source: https://github.com/glushkovds/phpclickhouse-laravel

Calling save() on an instance where $exists is true throws a generic PHP Exception with message 'Clickhouse does not allow update rows'. The example shows catching it after create() sets $exists to true.

```php
try {
    $model = MyTable::create(['model_name' => 'x']);
    $model->save(); // $model->exists === true after create()
} catch (\Exception $e) {
    // "Clickhouse does not allow update rows"
}
```

--------------------------------

### Basic select through DB facade

Source: https://github.com/glushkovds/phpclickhouse-laravel

Use the DB facade to run a parameterized SELECT query on the 'clickhouse' connection. The query uses a placeholder '?' for the value 'click'.

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

$connection = DB::connection('clickhouse');
$rows = $connection->select('SELECT * FROM events WHERE type = ?', ['click']);
```

--------------------------------

### Connection::createWithClient(array $config): self

Source: https://github.com/glushkovds/phpclickhouse-laravel

Static factory method that constructs a new Connection instance and builds a Cluster from the provided configuration. It is used by the clickhouse driver resolver and returns a fully initialized connection ready for querying.

```APIDOC
## [STATIC] Connection::createWithClient(array $config): self

### Description
Factory method used by the `clickhouse` driver resolver registered in `ClickhouseServiceProvider::boot()`. It constructs the connection and builds a `Cluster` from the config.

### Method
Static method

### Endpoint
`Connection::createWithClient(array $config): self`

### Parameters
#### Method Parameters
- **$config** (array) - Required - Connection config: `database` (used as the connection database name), `cluster` (optional, list of node configs), plus every key documented in configuration.md. The provider injects a `name` key before calling this method.

### Response
#### Success Response
Returns a fully constructed `self` whose `getClient()` is ready to query.

### Behavior
- Sub-connection construction: `new static(null, $config['database'], '', $config)` (no PDO, no read PDO).
- If `$config['cluster']` exists, each node config is merged with the base config: `$nodeConfigs[] = $node + $config;` (node keys win). Otherwise a single node uses the config itself.
- The resulting node list is handed to `new Cluster($nodeConfigs)`.
```

--------------------------------

### slideNode() method signature with docblock

Source: https://github.com/glushkovds/phpclickhouse-laravel

Switches active node to the next available node. Cycles to the next pingable node, lazy-creating clients and swallowing TransportException.

```php
/**
 * Switch active node to the next available node
 * @return void
 */
public function slideNode(): void
```

--------------------------------

### compileSettingsComponent implementation

Source: https://github.com/glushkovds/phpclickhouse-laravel

Compiles a settings array into a SETTINGS clause for ClickHouse queries. Integer values render as key=value, other values as key='value'. Empty settings produce an empty string.

```php
if (empty($settings)) {
    return "";
}
$strAr = [];
foreach ($settings as $k => $v) {
    $strAr[] = is_int($v) ? "$k=$v" : "$k='$v'";
}
return 'SETTINGS ' . implode(', ', $strAr);
```

--------------------------------

### min($column), max($column), sum($column), avg($column), average($column)

Source: https://github.com/glushkovds/phpclickhouse-laravel

Aggregate methods that delegate to the `aggregate` method. `sum()` returns 0 when the aggregate is falsy; `average()` is an alias of `avg()`.

```APIDOC
## min($column), max($column), sum($column), avg($column), average($column)

### Description
Aggregate methods that delegate to the `aggregate` method. `sum()` returns 0 when the aggregate is falsy; `average()` is an alias of `avg()`.

### Method
min, max, sum, avg, average

### Parameters
- `$column` (string) - Required - Column to aggregate.

### Response
Returns the aggregate value.
```

--------------------------------

### select($select = ['*']): Builder (static)

Source: https://github.com/glushkovds/phpclickhouse-laravel

Creates a new Builder instance configured with the given select columns and the model's table. Returns a Builder.

```APIDOC
## select($select = ['*']): Builder (static)

### Description
Creates a new Builder instance configured as `select($select)->from($instance->getTable())` over a new query. Returns a `Builder`.

### Method
`select` (static)

### Parameters
- `$select` (string|array|RawColumn) - Optional - Default: `['*']` - Columns to select.

### Returns
`Builder`
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Set these environment variables in your .env file to configure the ClickHouse connection.

```dotenv
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=default
CLICKHOUSE_USERNAME=default
CLICKHOUSE_PASSWORD=
CLICKHOUSE_TIMEOUT_CONNECT=2
CLICKHOUSE_TIMEOUT_QUERY=2
CLICKHOUSE_HTTPS=false
CLICKHOUSE_RETRIES=0
CLICKHOUSE_MAX_PARTITIONS_PER_INSERT_BLOCK=300
CLICKHOUSE_FIX_DEFAULT_QUERY_BUILDER=true
```

--------------------------------

### Cluster constructor with nodeConfigs parameter

Source: https://github.com/glushkovds/phpclickhouse-laravel

Constructor that accepts an array of node configs. It iterates the configs, creates a client for each, pings it, and sets the active node index on the first success. If no node is available, it throws a TransportException.

```php
public function __construct(
    protected array $nodeConfigs
)
```

--------------------------------

### Blueprint-based table creation with SchemaBuilder::create()

Source: https://github.com/glushkovds/phpclickhouse-laravel

Creates a ClickHouse table using a blueprint. The first added column becomes the ORDER BY key. The compiled DDL follows a fixed shape: CREATE TABLE <name> (<columns>) ENGINE = MergeTree() ORDER BY (<first added column>).

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

$schema = DB::connection('clickhouse')->getSchemaBuilder();

$schema->create('my_table', function ($table) {
    $table->bigInteger('id');       // -> Int64, becomes ORDER BY (id)
    $table->string('field_one');    // -> String
    $table->timestamp('created_at'); // -> DateTime
});

// equivalent to:
// CREATE TABLE my_table (
//     id Int64,
//     field_one String,
//     created_at DateTime
// )
// ENGINE = MergeTree()
// ORDER BY (id)
```

--------------------------------

### Builder::settings() with SETTINGS clause

Source: https://github.com/glushkovds/phpclickhouse-laravel

Shows how to add a SETTINGS clause to a query using the builder grammar. The toSql() output includes the settings as shown in the comment.

```php
$builder = MyTable::select(['field_one'])->settings([
    'max_threads' => 3,
    'max_block_size' => '1000',
]);

// toSql() includes: ... SETTINGS max_threads=3, max_block_size='1000'
```

--------------------------------

### QueryGrammar::prepareParameters() parameter rewrite

Source: https://github.com/glushkovds/phpclickhouse-laravel

Rewrites query parameters from #@? placeholders to :0, :1 style named parameters. Applied inside Connection::select(). Output shows the transformed SQL.

```php
use PhpClickHouseLaravel\QueryGrammar;

$sql = 'SELECT * FROM events WHERE type = #@? AND id > #@?';
echo QueryGrammar::prepareParameters($sql);
// SELECT * FROM events WHERE type = :0 AND id > :1
```

--------------------------------

### createClient(array $config): Client

Source: https://github.com/glushkovds/phpclickhouse-laravel

Builds a ClickHouseDB\Client from the given configuration array. Applies database, timeouts, settings, and optional retries.

```APIDOC
## `createClient(array $config): Client` (protected static)

### Description
Builds a `ClickHouseDB\Client` from the config: creates a new client, sets the database, timeouts, settings, and optionally installs a retry curler.

### Method
`createClient` (static)

### Parameters
- `$config` (array) - Required - Configuration array containing `host`, `port`, `username`, `password`, `https`, `database`, `timeout_query`, `timeout_connect`, `settings`, and optionally `retries`.

### Returns
Configured `ClickHouseDB\Client`.
```

--------------------------------

### Querying Data

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

Use the fluent query builder to select, filter, group, and apply settings to your ClickHouse queries.

```php
$rows = MyTable::select(['field_one', new RawColumn('sum(field_two)', 'field_two_sum')])
    ->where('created_at', '>', '2020-09-14 12:47:29')
    ->groupBy('field_one')
    ->settings(['max_threads' => 3])
    ->getRows();
```

--------------------------------

### Builder constructor signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Constructor accepts optional ClickHouseDB\Client and connection name. Falls back to getThisClient() when client is null; defaults connection to Connection::DEFAULT_NAME. Sets grammar to new Grammar().

```php
public function __construct(?Client $client = null, ?string $connection = null)
```

--------------------------------

### statement($query, $bindings = []): bool

Source: https://github.com/glushkovds/phpclickhouse-laravel

Executes a write statement and returns true if the write succeeded, false otherwise.

```APIDOC
## statement($query, $bindings = []): bool

### Description
Executes a write statement and returns true if the write succeeded, false otherwise.

### Method
`statement`

### Signature
```php
public function statement($query, $bindings = []): bool
```

### Source
`src/Connection.php:78`

### Parameters
#### Parameters
- **$query** (string) - Required - SQL (parameter rewriting applied as in `select`).
- **$bindings** (array) - Optional - Default: `[]` - Bound values.

### Returns
- **bool** - `true` when `$this->cluster->getActiveNode()->write($query, $bindings)->isError()` is false; otherwise `false`.
```

--------------------------------

### Enable settings for lightweight updates

Source: https://github.com/glushkovds/phpclickhouse-laravel/blob/master/README.md

One-time per table, enable the required settings for lightweight updates. This ALTER TABLE statement sets enable_block_number_column and enable_block_offset_column to 1.

```php
MyTable::getClient()->write(
    'ALTER TABLE my_table MODIFY SETTING enable_block_number_column = 1, enable_block_offset_column = 1'
);
```

--------------------------------

### select($query, $bindings = [], $useReadPdo = true, array $fetchUsing = []): array

Source: https://github.com/glushkovds/phpclickhouse-laravel

Executes a SELECT query and returns the result rows as an array of associative arrays. The SQL is rewritten by QueryGrammar::prepareParameters() before execution.

```APIDOC
## select($query, $bindings = [], $useReadPdo = true, array $fetchUsing = []): array

### Description
Executes a SELECT query and returns the result rows as an array of associative arrays. The SQL is rewritten by `QueryGrammar::prepareParameters($query)` before execution.

### Method
`select`

### Signature
```php
public function select($query, $bindings = [], $useReadPdo = true, array $fetchUsing = []): array
```

### Source
`src/Connection.php:69`

### Parameters
#### Parameters
- **$query** (string) - Required - SQL, optionally containing `?` placeholders written by `QueryGrammar::parameter()`.
- **$bindings** (array) - Optional - Default: `[]` - Bound values in parameter order.
- **$useReadPdo** (bool) - Optional - Default: `true` - Accepted for interface compatibility; ignored (there is no read PDO).
- **$fetchUsing** (array) - Optional - Default: `[]` - Accepted for interface compatibility; ignored.

### Returns
- **array** - Array of result rows (each row is an associative array).
```

--------------------------------

### query()

Source: https://github.com/glushkovds/phpclickhouse-laravel

Returns a query builder. With 'fix_default_query_builder' => true in the connection config, returns PhpClickHouseLaravel\Builder; otherwise falls back to Illuminate\Database\Query\Builder.

```APIDOC
## query()

### Description
Returns a query builder. With `'fix_default_query_builder' => true` in the connection config, returns `PhpClickHouseLaravel\Builder` (the Tinderbox-based builder). Otherwise falls back to `Illuminate\Database\Query\Builder` — which is subject to the `whereIn` parameter-numbering bug documented in [docs/known_issues.md](../known_issues.md).

### Method
`query`

### Signature
```php
public function query()
```

### Source
`src/Connection.php:114`

### Returns
- **Builder** - A query builder instance.
```

--------------------------------

### all() method signature with docblock

Source: https://github.com/glushkovds/phpclickhouse-laravel

Returns rows in the same shape as Laravel's query builder collection. Converts each associative array row to a plain object.

```php
/**
 * Return rows in the same shape as Laravel's query builder collection.
 */
public function all(): array
```

--------------------------------

### __construct

Source: https://github.com/glushkovds/phpclickhouse-laravel

Constructor for the Builder class. Initializes the query builder with an optional ClickHouse client and Laravel connection name.

```APIDOC
## __construct

### Description
Constructor for the Builder class. Initializes the query builder with an optional ClickHouse client and Laravel connection name.

### Method
Constructor

### Signature
```php
public function __construct(?Client $client = null, ?string $connection = null)
```

### Parameters
- `$client` (?ClickHouseDB\Client) - Optional - Client to execute against. Falls back to `$this->getThisClient()` (via `WithClient`) when null.
- `$connection` (?string) - Optional - Laravel connection name for query logging / `resolveConnection()`. Defaults to `Connection::DEFAULT_NAME`.

### Notes
Sets `$this->grammar = new Grammar();` (the ClickHouse settings-aware grammar).
```

--------------------------------

### slideNode(): void

Source: https://github.com/glushkovds/phpclickhouse-laravel

Cycles the active node to the next available pingable node. If fewer than 2 node configs exist, returns immediately.

```APIDOC
## slideNode(): void

### Description
Cycles the active node to the next available pingable node. If fewer than 2 node configs exist, returns immediately. Iterates at most `$configCount` times; computes `$nextIndex = $this->activeNodeIndex + 1`, wrapping to `0` at the end. Lazy-creates the next client if missing: `$this->nodes[$nextIndex] ??= static::createClient(...)`. `ping(true)`s the candidate; on success sets `activeNodeIndex` and stops; `TransportException` is swallowed and the next index is tried.

### Method
GET

### Endpoint
`slideNode()`

### Response
#### Success Response
- **void** - No return value
```

--------------------------------

### aggregate method signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Runs a clone without columns (unless unions or havings are present) and returns the aggregate value or null.

```php
public function aggregate($function, $columns = ['*'])
```

--------------------------------

### Basic create and query with BaseModel

Source: https://github.com/glushkovds/phpclickhouse-laravel

Defines a ClickHouse model extending PhpClickHouseLaravel\BaseModel and shows single-row creation, bulk inserts (non-associative and associative), and a query using where()->getRows(). The 'creating' event is not used here; see the next snippet for event halting.

```php
namespace App\Models\Clickhouse;

use PhpClickHouseLaravel\BaseModel;

class MyTable extends BaseModel
{
    protected $table = 'my_table';
}

// insert single row
$model = MyTable::create(['model_name' => 'model 1', 'some_param' => 1]);
echo $model->wasRecentlyCreated ? 'inserted' : 'not inserted';

// bulk (non-associative)
MyTable::insertBulk([['model 1', 1], ['model 2', 2]], ['model_name', 'some_param']);

// bulk (associative)
MyTable::insertAssoc([
    ['model_name' => 'model 1', 'some_param' => 1],
    ['some_param' => 2, 'model_name' => 'model 2'],
]);

// query
$rows = MyTable::where('some_param', '>', 1)->getRows();
```

--------------------------------

### Check for false return from BaseModel::create() when creating event halts

Source: https://github.com/glushkovds/phpclickhouse-laravel

When a 'creating' event listener returns false, BaseModel::create() returns false instead of a model instance and no insert runs. Use this check to detect the halt.

```php
$model = MyTable::create(['model_name' => 'invalid']);
if ($model === false) {
    // creation was halted by a 'creating' listener
}
```

--------------------------------

### Schema-builder migration with custom connection and error handling

Source: https://github.com/glushkovds/phpclickhouse-laravel

Uses createMergeTree() with a fluent column DSL on a custom connection 'clickhouse2'. The closure defines columns and order by. Note that write() delegates to Cluster::write(), so an unavailable node throws TransportException; wrap up() to surface failures.

```php
<?php

return new class extends \PhpClickHouseLaravel\Migration
{
    protected $connection = 'clickhouse2';

    public function up()
    {
        static::createMergeTree('my_table', function (\PhpClickHouseSchemaBuilder\Tables\MergeTree $table) {
            $table->columns([
                $table->uInt32('id'),
                $table->datetime('created_at', 3)->default(new \Tinderbox\ClickhouseBuilder\Query\Expression('now64()')),
                $table->string('field_one'),
                $table->int32('field_two'),
            ])->orderBy('id');
        });
    }

    public function down()
    {
        static::write('DROP TABLE my_table');
    }
};
```

```php
public function up()
{
    try {
        static::write('CREATE TABLE my_table ...');
    } catch (\ClickHouseDB\Exception\TransportException $e) {
        throw new \RuntimeException('ClickHouse migration failed: ' . $e->getMessage());
    }
}
```

--------------------------------

### Aggregate method signatures (min, max, sum, avg, average)

Source: https://github.com/glushkovds/phpclickhouse-laravel

Each delegates to aggregate(__FUNCTION__, [$column]). sum() returns 0 when the aggregate is falsy; average() is an alias of avg().

```php
public function min($column)      // src/BuilderMethodsFromLaravel.php:163
public function max($column)      // src/BuilderMethodsFromLaravel.php:174
public function sum($column)      // src/BuilderMethodsFromLaravel.php:185
public function avg($column)      // src/BuilderMethodsFromLaravel.php:198
public function average($column)  // src/BuilderMethodsFromLaravel.php:209
```

--------------------------------

### registerDefaultConnectionConfig() method signature

Source: https://github.com/glushkovds/phpclickhouse-laravel

Protected method that sets database.connections.clickhouse with defaults merged.

```php
protected function registerDefaultConnectionConfig(): void
```
Tokens:
Raw