README

cboxdk/laravel-billing-clickhouse — a ClickHouse-backed EventLog for cboxdk/laravel-billing, for event-heavy, high-cardinality metering where the relational event log would strain.

ClickHouse is optional: small/most deployments use the relational event log that ships with billing. Install this only when your usage volume calls for a columnar store — the EventLog contract is identical, so nothing calling it changes.

Install

composer require cboxdk/laravel-billing-clickhouse

// .env
CLICKHOUSE_DSN=http://localhost:8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=

With a DSN set, billing's Cbox\Billing\Metering\Contracts\EventLog is bound to the ClickHouse adapter. Create the table once:

app(\Cbox\Billing\ClickHouse\ClickHouseEventLog::class)->migrate();

Design

• HTTP interface, no heavy SDK. Talks to ClickHouse over its HTTP endpoint via the Laravel HTTP client, so the append/sum logic is fully testable with Http::fake.
• Idempotent by table engine. A ReplacingMergeTree keyed on the event id collapses duplicates on merge; sum deduplicates by event id at query time, so it is correct even before a merge runs. Query parameters are bound, not interpolated.

Verify against a live ClickHouse before relying on it in production.

Requirements

PHP ^8.4; Laravel ^12 || ^13; cboxdk/laravel-billing.

License

MIT.