feat: migrate ClickHouse adapter to utopia-php/query 0.3.x builder

[lohanidamodar]

Summary

Migrates the ClickHouse adapter to utopia-php/query 0.3.x (stable pin 0.3.*, resolving to the tagged 0.3.3 release — no dev-branch pins). Every table CREATE, materialized view, INSERT envelope, SELECT and DELETE now compiles through Schema\ClickHouse / Builder\ClickHouse; the adapter keeps only its HTTP transport, routing logic, and the few DDL shapes the library cannot express yet.

Rebased onto current main (7c3fbf1) as a single commit, so the migration now also covers everything that landed while this PR was open:

• premium geo dimension columns (Add premium geo dimension columns to usage events #21)
• retention TTL on the raw events table and on events_daily, including the REMOVE TTL guard anchored on error code 36 (feat(clickhouse): optional retention TTL on the raw events table #24, feat(clickhouse): extend retention TTL to the events_daily table #27)
• sdk / sdkVersion dimension columns (Add sdk and sdkVersion dimension columns to usage events #25)
• ordinal gauge dimension column (feat: add ordinal gauge dimension column #26)
• contains aligned with utopia-php/database substring semantics (Align contains query with utopia-php/database semantics #28)

What changed

Schema (DDL via Schema\ClickHouse)

• createTable() emits the events/gauges tables through Table\ClickHouse: typed columns with codec(), Engine::MergeTree, partitionBy, orderBy, settings.
• createDailyTable() uses Engine::SummingMergeTree; createDailyMaterializedView() goes through Schema\ClickHouse::createMaterializedView (the MV body remains a hand SELECT — subquery-aggregation MV bodies do not round-trip through the builder yet).
• Column shapes the typed API cannot express are emitted via rawColumn() so the deployed DDL stays byte-for-byte identical: DateTime64(3, 'UTC') (timezone argument), LowCardinality(Nullable(String)) (the typed API emits the invalid Nullable(LowCardinality(...)) nesting), and the hyphenated skip-index names (index-path), which the typed index API rejects.
• Projections (ADD PROJECTION), MODIFY SETTING, the ADD COLUMN IF NOT EXISTS dim backfills and the retention MODIFY TTL / REMOVE TTL ALTERs stay raw SQL — no schema-layer support yet. The new geo / sdk / sdkVersion / ordinal columns flow into both the schema-layer CREATE and the raw backfill path automatically, since both read from Metric::getEventSchema() / getGaugeSchema().

Reads (SELECT via Builder\ClickHouse)

• Every builder is initialised with useNamedBindings() + withParamTypes(); all schema columns are pinned to their ClickHouse parameter types (DateTime64(3, 'UTC'), Int64, String) so placeholders never fall back to PHP value inference.
• Migrated: find/findFromTable, findAggregatedFromTable (interval buckets + dim group-bys), count (including the bounded LIMIT max subquery), sum and the routed daily/hybrid paths, findDaily, sumDaily, sumDailyBatch, getTotal*, getTimeSeries.
• The hybrid daily+raw sum compiles its two sides as independent builder statements and merges them under SUM(...) FROM (... UNION ALL ...), prefixing one side's named bindings to avoid placeholder collisions.
• Cursor pagination keeps the tuple-keyset comparison as a whereRaw fragment with its own named bindings (upstream builder helper deferred).
• contains() / containsAny() / notContains() now pass straight through to the builder. The 0.3 ClickHouse builder compiles them to position(column, ?), which is the same substring semantics Align contains query with utopia-php/database semantics #28 introduced, and matches needles literally — so the adapter no longer needs its own escapeLikeWildcards() helper for % / _. The adapter still validates that every needle is a string and still rejects empty value lists.

Writes

• addBatch() compiles the INSERT INTO t (...) FORMAT JSONEachRow envelope via insertFormat(); JSONEachRow body assembly and the non-retrying POST transport are unchanged.

Deletes

• purge() / purgeDaily() emit lightweight DELETE FROM through the builder.

Query 0.3 API surface

• Query::getMethod() returns the Method enum, so all string TYPE_* comparisons are gone (ClickHouse and Database adapters).
• BREAKING: the UsageQuery::TYPE_GROUP_BY_INTERVAL / TYPE_GROUP_BY string constants are removed. UsageQuery::groupByInterval() and UsageQuery::groupBy() remain and now map to Method::GroupByTimeBucket / Method::GroupBy; groupBy() also accepts an array of columns to stay signature-compatible with the 0.3 base class.
• composer.lock moves utopia-php/query 0.1.1 -> 0.3.3 and nothing else; utopia-php/validators and utopia-php/database stay on main's pins.

Test plan

• CI Linter (Pint, psr12) — pass
• CI CodeQL job, which runs composer check (PHPStan level max over src + tests) — pass
• CI Tests on the pinned docker-compose.yml stack (ClickHouse 25.11 + MariaDB 10.7) — OK (264 tests, 1305 assertions)

Locally the rebase was additionally verified without Docker, against a natively installed ClickHouse 26.8.1 + MariaDB 11.8.8: 264 tests, 1293 assertions, 2 failures, 0 errors, and an origin/main (7c3fbf1) run on the exact same servers produced an identical result — same two tests, same assertion count. Those two, ClickHouseSchemaTest::testEventsTableSwapsBloomForSetOnLowCardinality and ::testGaugesTableSwapsBloomForSetOnLowCardinality, are a ClickHouse-version artefact: 26.x renders skip indexes as INDEX `index-status` (status) TYPE set(0) (parenthesised column list) where 25.11 renders INDEX `index-status` status TYPE set(0), and the assertions expect the un-parenthesised form. They pass on CI's 25.11 image.

Green coverage includes the SHOW CREATE TABLE schema assertions (codecs, LowCardinality(Nullable(String)), DateTime64(3, 'UTC'), hyphenated index-* names), projection/dim-routing, cursor pagination, purge propagation, the retention-TTL tests, and the contains wildcard-escaping e2e test added in #28.

Still deferred upstream (follow-up PRs)

• Tuple-cursor builder helper (cursor pagination still uses whereRaw)
• LowCardinality(Nullable(...)) column type and timezone argument for DateTime64
• Skip-index names containing hyphens
• Projections / MODIFY SETTING / ADD COLUMN IF NOT EXISTS / MODIFY TTL in the schema layer
• MV bodies with aggregation subqueries

[greptile-apps]

Greptile Summary

Migrates the ClickHouse adapter to the query 0.3.x schema and builder APIs.

• Pins utopia-php/query to stable 0.3.x and adopts enum-based query methods.
• Compiles ClickHouse DDL, reads, inserts, and deletes through the new builder where supported.
• Adds typed named bindings, tenant-aware filtering, and tests for migrated query behavior.

Confidence Score: 3/5

The PR is not yet safe to merge because getTimeSeries still rejects intervals supported by the library’s grouped-query API.

The stable dependency and static-analysis cleanup are in place, but the time-series path still validates and compiles through a map containing only 1h and 1d while the shared interval API supports additional minute, week, and month buckets.

Files Needing Attention: src/Usage/Adapter/ClickHouse.php

Important Files Changed

Filename	Overview
src/Usage/Adapter/ClickHouse.php	Migrates ClickHouse SQL construction to the 0.3.x builder and schema APIs; the previously reported time-series interval inconsistency remains.
src/Usage/Adapter/Database.php	Updates query-method comparisons to the Method enum.
src/Usage/UsageQuery.php	Adapts group-by factories and interval metadata to the query 0.3.x API.
composer.json	Replaces the earlier query dependency with the stable 0.3.x constraint.
composer.lock	Locks utopia-php/query 0.3.3 and its resolved metadata.
tests/Usage/Adapter/ClickHouseTest.php	Expands coverage for builder-generated ClickHouse behavior, though time-series tests remain limited to 1h and 1d.
tests/Usage/UsageQueryTest.php	Updates query tests for enum methods and the supported interval set.
CHANGELOG.md	Documents the query 0.3.x migration and public compatibility changes.

_{Reviews (7): Last reviewed commit: "feat!: migrate ClickHouse adapter to uto..." | Re-trigger Greptile}

[abnegate]

Let's keep the docs on public methods

[lohanidamodar]

Restored docblocks on the public setter / lifecycle methods that lost them during the migration rewrite (__construct, setTimeout, enableQueryLogging, setCompression, setKeepAlive, setMaxRetries, setRetryDelay, setAsyncInserts, clearQueryLog, getName, healthCheck, setNamespace, setDatabase, setSecure, plus the namespace/tenant/sharedTables getters). Done in 0e0bbd6.

[abnegate]

There should be shorthand methods we can use for integer, float and boolean too

[lohanidamodar]

Swapped the addColumn(..., ColumnType::BigInteger|Float|Boolean) calls in the match block to the dedicated bigInteger() / float() / boolean() shorthand, plus the value BigInteger column in createDailyTable(). ColumnType import is no longer needed. SQL snapshot tests still green. Done in c2a261e.