Skip to content
CLICKHOUSE-TOOLKIT(3)rasuvaeff PHP Library ManualCLICKHOUSE-TOOLKIT(3)

NAME ​

clickhouse-toolkit — framework-agnostic ClickHouse query builder, readers, writers and migrations for PHP

SYNOPSIS ​

$ 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);

DESCRIPTION ​

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.
  • Allow-listed fields, and 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.

EXAMPLES ​

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

SEE ALSO ​

PackageRole
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

BUGS ​

Migration rollback is intentionally not included. Use forward-fix migrations with idempotent DDL.

DEPENDENCIES

requires: context(3)

required by: yii3-ab-testing-clickhouse(3), yii3-clickhouse-toolkit(3), yii3-outbox-clickhouse(3)

HISTORY

First released as v1.0.0 on 2026-05-30; 18 releases in all.

v1.12.02026-10-17
v1.11.12026-10-15
v1.11.02026-10-15
v1.10.12026-10-11
v1.10.02026-10-10
v1.9.02026-09-13
v1.8.02026-09-11
v1.7.02026-09-10
v1.6.02026-07-25
v1.5.12026-07-25

… and 8 earlier. All releases

rasuvaeff/clickhouse-toolkit 1.12.0mutation gate 95%used by 3 packagesCLICKHOUSE-TOOLKIT(3)

/ search · n N next, previous · g G top, bottom · q back to the index