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

This PR migrates the ClickHouse adapter, UsageQuery, and the Database adapter from the removed Query::TYPE_* string constants to the Method enum surface introduced in utopia-php/query 0.3.x, while also compiling all DDL, SELECT, INSERT, and DELETE operations through the typed named-binding builder and schema layers.

• Schema (DDL): createTable, createDailyTable, and createDailyMaterializedView now go through Schema\ClickHouse / Table\ClickHouse; columns the typed API cannot yet express (e.g., DateTime64(3,'UTC'), LowCardinality(Nullable(String)), hyphenated index names) fall back to rawColumn() so the deployed DDL stays byte-for-byte identical.
• Reads (SELECT): Every query path uses useNamedBindings() + withParamTypes() with per-column ClickHouse type pins; the hybrid daily+raw UNION ALL prefixes one side's bindings via prefixNamedBindings() to prevent key collisions.
• Writes / Deletes: addBatch() now compiles the INSERT INTO … FORMAT JSONEachRow envelope via insertFormat(); purge()/purgeDaily() use the builder's DELETE FROM path.

Confidence Score: 5/5

• Safe to merge — the migration is a mechanical but well-scoped replacement of string-based SQL assembly with the typed builder API, and the deployed DDL and query semantics remain unchanged.
• All SQL compilation now goes through typed named bindings with no string interpolation of user values. The hybrid UNION ALL path correctly prefixes one side's bindings to avoid collisions. The schema DDL falls back to rawColumn() for column types the library cannot yet express, keeping the actual table definitions byte-for-byte identical. CI reports 264 tests passing on the target ClickHouse version. The only items left in the review are style notes about hardcoded interval strings in the fill helpers.
• No files require special attention; the fill-helper style notes in src/Usage/Adapter/ClickHouse.php are non-blocking.

Important Files Changed

Filename	Overview
src/Usage/Adapter/ClickHouse.php	Core migration: all DDL, SELECT, INSERT, and DELETE paths now compile through utopia-php/query 0.3.x builders with typed named bindings. One style concern: the zero-fill/locf fill helpers hardcode an === '1h' branch rather than using the same central interval map used by getTimeSeries's allowlist guard.
src/Usage/UsageQuery.php	Migrated from removed TYPE_* string constants to Method enum values; VALID_INTERVALS gains 30m; groupBy() now accepts `array
src/Usage/Adapter/Database.php	All TYPE_* string comparisons replaced with Method enum cases in convertQueriesToDatabase. Straightforward mechanical update, no logic changes.
composer.json	Dependency flipped from the dev-branch alias to the stable 0.3.* pin with minimum-stability: stable restored, resolving the previously flagged mutability concern.

_{Reviews (8): Last reviewed commit: "Merge origin/main into feat/utopia-query..." | 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.