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 snapshot table (ReplacingMergeTree) via a new setRetention(?int $days) method that drives an idempotent ALTER TABLE … MODIFY/REMOVE TTL in setup(). The aggregated billing table is intentionally left untouched.

• setRetention() validates that days is positive and returns $this for chaining; getRetention() exposes the current value.
• setup() either applies MODIFY TTL … SETTINGS materialize_ttl_after_modify = 0 (deferred purge) or runs REMOVE TTL and swallows the error when the table has no TTL, keeping setup() fully re-runnable. Both previously flagged issues — null retention not removing an existing TTL, and the property being protected — are now resolved.

Confidence Score: 5/5

Safe to merge; the TTL logic is well-scoped and idempotent, and the two previously identified issues have been corrected.

The change is narrow (one file, two new public methods, one DDL block in setup()), the snapshot-only scope is clearly enforced, and setup() remains re-runnable in all three states: never had TTL, has TTL, had TTL removed. The only open point is that the catch block for REMOVE TTL matches an English error substring rather than a stable error code, but this does not affect current correctness.

No files require special attention.

Important Files Changed

Filename	Overview
src/Usage/Adapter/ClickHouse.php	Adds optional retention TTL to the snapshot table via setRetention()/getRetention() and an idempotent MODIFY/REMOVE TTL block in setup(). Previously flagged issues (null-retention not stripping TTL, protected vs private) are both addressed. One minor robustness concern around string-based error matching in the REMOVE TTL catch block.

_{Reviews (3): Last reviewed commit: "fix(clickhouse): tolerate REMOVE TTL on ..." | Re-trigger Greptile}