clickhouse-toolkit — framework-agnostic ClickHouse query builder, readers, writers and migrations for PHP
$ composer require rasuvaeff/clickhouse-toolkit
$qb = new ClickHouseQueryBuilder( allowedFields: ['id', 'status', 'created_at'], fieldTypes: ['id' => T::UInt64, 'created_at' => T::DateTime], defaultSort: 'id DESC',); $where = $qb->buildWhere(new In('status', ['active', 'pending']));$orderBy = $qb->buildOrderBy(Sort::only(['created_at'])->withOrder(['created_at' => 'desc']));$sql = $qb->buildSelect(table: 'events', columns: ['id', 'status'], where: $where->sql, orderBy: $orderBy, limit: 20);
Framework-agnostic ClickHouse helpers for PHP, built on simpod/clickhouse-client, with query and reader pieces that plug into yiisoft/data.
ClickHouse has its own SQL dialect, async mutations, partitions and batch inserts, and a query built from user filters is an injection risk. This toolkit covers those parts with parameterized SQL and an allow-list.
ClickHouseClientFactory and ClickHouseConfig build a client over any PSR-18 HTTP client.ClickHouseQueryBuilder turns yiisoft/data filters and sorting into parameterized SQL.withMandatoryFilter() for tenant or ACL constraints.ClickHouseDataReader is an immutable DataReaderInterface for yiisoft/data paginators.ClickHouseKeysetReader streams large result sets with bounded memory.ClickHouseBatchWriter does buffered, batched inserts.ClickHouseTableBuilder for fluent CREATE TABLE; ClickHousePartitionManager for partitions.ClickHouseMutationBuilder for async ALTER UPDATE / DELETE with mutation tracking.ClickHouseMigrationRunner: idempotent, checksum-verified .sql migrations.Batch-inserts rows with ClickHouse async_insert settings applied to every INSERT.
$writer = new ClickHouseBatchWriter( client: $client, table: 'events', columns: ['id', 'type', 'user_id', 'created_at'], batchSize: 10_000, settings: ['async_insert' => 1, 'wait_for_async_insert' => 0],);
Creates a partitioned MergeTree table with a fluent DDL builder.
ClickHouseTableBuilder::create($client, 'events') ->ifNotExists() ->column('id', T::UInt64) ->column('created_at', T::DateTime) ->engine('MergeTree()') ->partitionBy('toYYYYMM(created_at)') ->primaryKey('id') ->orderBy('(id, created_at)') ->execute();
Lists MergeTree partitions with row and byte counts, then drops or archives one by id.
$pm = new ClickHousePartitionManager($client); foreach ($pm->getPartitions('events') as $p) { // ['partition' => '202401', 'partition_id' => '202401', 'rows' => 12345, 'bytes' => 987654]} $pm->dropPartition('events', '202401');$pm->movePartition('events', 'events_archive', '202401');MOVE … TO TABLE
| Package | Role |
|---|---|
| yii3-clickhouse-toolkit(3) | Yii3 config bridge and console commands |
| yii3-outbox-clickhouse(3) | Batched outbox exporter |
| yii3-ab-testing-clickhouse(3) | A/B analytics schema and migrations |
| context(3) | Request budget mapped to max_execution_time |
Migration rollback is intentionally not included. Use forward-fix migrations with idempotent DDL.
requires: context(3)
required by: yii3-ab-testing-clickhouse(3), yii3-clickhouse-toolkit(3), yii3-outbox-clickhouse(3)
First released as v1.0.0 on 2026-05-30; 18 releases in all.
| v1.12.0 | 2026-10-17 |
| v1.11.1 | 2026-10-15 |
| v1.11.0 | 2026-10-15 |
| v1.10.1 | 2026-10-11 |
| v1.10.0 | 2026-10-10 |
| v1.9.0 | 2026-09-13 |
| v1.8.0 | 2026-09-11 |
| v1.7.0 | 2026-09-10 |
| v1.6.0 | 2026-07-25 |
| v1.5.1 | 2026-07-25 |
… and 8 earlier. All releases
/ search · n N next, previous · g G top, bottom · q back to the index