feat(clickhouse): add optional retention TTL on the snapshot table

[levivannoort]

What

Adds setRetention(?int $days) to the ClickHouse usage adapter. When set, setup() applies an idempotent TTL to the snapshot (ReplacingMergeTree) table so latest-state rows past the retention window are dropped by background merges:

$adapter->setRetention(30);
$usage->setup(); // ALTER TABLE {ns}_usage_snapshot ... MODIFY TTL toDateTime(time) + INTERVAL 30 DAY

Default null preserves current behaviour (no TTL).

Scope: snapshot only

Only the snapshot table gets a TTL. The aggregated {ns}_usage (SummingMergeTree) table is intentionally left untouched — it backs long-term usage/billing history, so dropping rows there would delete billing data.

Why in setup()

Retention is part of the table's schema, and setup() already owns everything else about it. Keeping TTL here means callers that already run setup() get retention with no extra plumbing, and no downstream code has to re-derive table names.

How

• Applied as a separate ALTER … MODIFY TTL, not baked into CREATE TABLE, since CREATE TABLE IF NOT EXISTS won't touch an existing table. MODIFY TTL is a no-op when unchanged, so setup() stays idempotent/re-runnable.
• SETTINGS materialize_ttl_after_modify = 0 defers the purge to normal background merges instead of an immediate mutation.
• time is DateTime64(3); toDateTime(time) narrows it for the TTL expression.
• setRetention() rejects non-positive day counts.

Pint (composer lint) and PHPStan level max (composer check) pass on the changed file.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR adds an optional retention TTL to the ClickHouse adapter's snapshot (ReplacingMergeTree) table. When setRetention($days) is called before setup(), the table gets an idempotent MODIFY TTL applied; when retention is null (the default), setup() runs REMOVE TTL so any previously-set TTL is actively cleared.

• setRetention(?int $days) validates positive values and returns self for fluent chaining; the backing field is correctly private with no subclass bypass.
• setup() now unconditionally reconciles the snapshot table's TTL state on every run — applying MODIFY TTL … INTERVAL N DAY or REMOVE TTL — keeping the method idempotent and self-contained.

Confidence Score: 5/5

Safe to merge. The change is narrowly scoped to schema management in setup(), the property is private with a validated setter, and both retention paths (apply TTL / remove TTL) are present and idempotent.

The new TTL logic is well-contained: injection risk is eliminated because $this->retention is always a validated positive integer or null before it reaches the SQL string. The REMOVE TTL branch ensures the snapshot table's TTL state is always reconciled to the caller's intent on every setup() run. Both concerns raised in prior review threads are addressed in this revision. No new defects were identified.

No files require special attention.

Important Files Changed

Filename	Overview
src/Usage/Adapter/ClickHouse.php	Adds optional retention TTL on the snapshot table: setRetention(?int $days) / getRetention() methods, private property with positive-integer guard, and idempotent MODIFY TTL / REMOVE TTL branches in setup(). Both previously-raised issues (protected visibility, missing REMOVE TTL for null) are resolved.

_{Reviews (2): Last reviewed commit: "fix(clickhouse): remove TTL when retenti..." | Re-trigger Greptile}