Extract multitenancy into a SharedTables decorator with safe withTenant scoping

[loks0n]

Why

The ClickHouse adapter baked multi-tenancy in via mutable setNamespace/setSharedTables/setTenant setters — and each flushed the buffer. setTenant per message (multi-tenant workers) meant one ClickHouse round-trip per message, which in Appwrite Cloud's stats-usage worker capped throughput at ~1 message per cross-region round-trip and OOM'd the queue.

This pulls multitenancy out of the core adapter entirely so the failure pattern isn't even expressible, and gives reads a tenant scope that's safe under concurrency.

Design

Base ClickHouse is now strictly single-tenant — no tenant column, no tenant SQL. Multi-tenancy lives in a SharedTables subclass that controls SQL generation through protected seams on the base:

seam	role
tenantColumnDefs()	tenant column on every table
keyPrefix()	tenant as the leading ORDER BY / projection / GROUP BY key
extraQueryableColumns()	tenant accepted as a query attribute
scopeOnlyAttributes()	tenant scopes but never narrows a daily purge
scopeQueries()	inject the active tenant filter on reads/purges
decorateRow()	stamp the per-row tenant on writes

Tenant is no longer adapter state, nor a parameter on every read method. Instead:

• Reads/purges scope through SharedTables::withTenant($tenant, fn($scoped) => …), which hands the callback a tenant-bound clone — no shared mutable state, safe under concurrent coroutines, and the scope can't leak past the closure. Usage::withTenant mirrors it for the wrapper.
• Writes keep the per-row $tenant on collect(), so one buffer still batches many tenants in a single flush (the throughput win).

// write: many tenants, one buffer, one flush
$usage->collect('network.requests', 5, Usage::TYPE_EVENT, $tags, tenant: $projectId);

// read: scoped, safe, auto-cleared
$total = $usage->withTenant($projectId, fn (Usage $u) =>
    $u->getTotal('network.requests', [], Usage::TYPE_EVENT));

Notable

• Daily-purge safety fix: tenant is treated as a scope, not a narrowing filter, so a path-only purge can't fall through to DELETE … WHERE tenant=X and wipe a tenant's unrelated daily rows.
• Database adapter reverted to no tenant params (keeps its own backend tenant handling).

Migration (breaking)

• new ClickHouse(host, user, pass, port, secure) → new SharedTables(host, user, pass, port, secure, namespace) for multi-tenant; base ClickHouse is single-tenant.
• ->setNamespace()/->setSharedTables()/->setTenant() removed; namespace is a constructor arg.
• Reads: scope via withTenant(). Writes: collect(..., tenant: $t).

Tests

247 tests green against ClickHouse + MariaDB (docker-compose); PHPStan level max and Pint clean on src and changed tests. Added explicit withTenant override + cross-tenant isolation tests. Shared-mode tests pin a tenant via a ScopedClickHouse extends SharedTables helper, still exercising the real tenant SQL.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR extracts multi-tenancy out of the core ClickHouse adapter and into a new SharedTables subclass, fixing a critical throughput issue where setTenant() flushed the buffer on every call. Tenant state is no longer mutable adapter state; reads scope via a transient clone from withTenant(), and writes stamp the per-row tenant on collect(), letting a single buffer batch many tenants.

• ClickHouse becomes strictly single-tenant with six protected seam methods (tenantColumnDefs, keyPrefix, extraQueryableColumns, scopeOnlyAttributes, scopeQueries, decorateRow) that SharedTables overrides to add all tenant SQL in one place.
• SharedTables::withTenant hands the callback a tenant-bound shallow clone so the scope cannot leak across coroutines or past the closure; Usage::withTenant mirrors this at the wrapper layer and degrades gracefully on single-tenant adapters.
• purgeDaily now correctly separates scope-only (tenant) queries from narrowing queries so a path-only purge cannot silently fall through to a tenant-wide daily delete.

Confidence Score: 5/5

Safe to merge; the core refactoring is architecturally sound and the concurrency guarantee (scoped clone, no shared mutable tenant state) is correctly implemented.

The tenant-scoping logic is correct across all public read paths. The purge/daily-purge split properly separates scope-only and narrowing queries. The three issues noted are design polish rather than data correctness problems: redundant tenant filters on the daily routing path produce SQL that is logically equivalent to a single filter, the Nullable(String) type hint mismatch only matters for null bindings which never occur in the active scope path, and the shared HTTP client concern only applies to coroutine runtimes not yet in scope.

ClickHouse.php deserves a second look at the interaction between sum()/getTotal() and sumDaily() in the daily routing path, where scopeQueries runs twice on the same query set.

Important Files Changed

Filename	Overview
src/Usage/Adapter/SharedTables.php	New class implementing multi-tenancy via decorator seams; clean design with scoped clone pattern in withTenant()
src/Usage/Adapter/ClickHouse.php	Multi-tenancy extracted into overridable seam methods; scopeQueries() is called at all public entry points but sumDaily/findDaily/sumDailyBatch are also called internally by routedSum, causing the tenant filter to be injected twice in the daily routing path
src/Usage/Usage.php	withTenant() delegates to adapter clone when available; collect() correctly includes tenant in the buffer key so a single buffer holds many tenants
src/Usage/Adapter/Database.php	Reverted to no tenant params on read methods; setTenant() still persists state on the underlying db object, which means tenant scope leaks across calls when passed null (previously flagged in this PR)
src/Usage/Adapter.php	Doc-comment formatting cleanup only; no functional changes
tests/Usage/Adapter/ScopedClickHouse.php	New test helper that pins a tenant via SharedTables subclass for exercising real tenant SQL in tests

_{Reviews (2): Last reviewed commit: "refactor: move multitenancy into a Share..." | Re-trigger Greptile}