When to enable it
Stay on Postgres first, then add ClickHouse for scale.
ClickHouse is most helpful once you want heavier event analytics or larger retention windows. The core app still uses PostgreSQL for users, projects, memberships, and API keys.
Environment
Set the ClickHouse connection variables explicitly.
shell
LOGISTER_CLICKHOUSE_ENABLED=true
LOGISTER_CLICKHOUSE_URL=http://127.0.0.1:8123
LOGISTER_CLICKHOUSE_DATABASE=logister
LOGISTER_CLICKHOUSE_EVENTS_TABLE=events_raw
LOGISTER_CLICKHOUSE_USERNAME=default
LOGISTER_CLICKHOUSE_PASSWORD=
REDIS_URL=redis://127.0.0.1:6379/0LOGISTER_CLICKHOUSE_URL can point at either a native ClickHouse HTTP endpoint or a ClickHouse Query API endpoint.
Schema setup
Initialize schema and keep the starter SQL nearby.
- Schema and materialized view:
docs/clickhouse_schema.sql - Starter dashboard queries:
docs/clickhouse_dashboard_queries.sql
shell
cat docs/clickhouse_schema.sql | curl "http://127.0.0.1:8123" --data-binary @-Health checks
Use the ClickHouse health endpoint to verify the dependency.
GET /health/clickhousereturns200when disabled or healthyGET /health/clickhousereturns503when enabled but unreachable
Payload mapping
Know how Logister event payloads land in ClickHouse columns.
| ClickHouse column | Payload source |
|---|---|
project_id | Authenticated API key project |
api_key_id | Authenticated API key id |
occurred_at | event.occurred_at with a Rails fallback if absent |
event_type | event.event_type |
level | event.level |
fingerprint | event.fingerprint or the generated fallback |
message | event.message |
environment | event.context.environment or Rails.env |
service | event.context.service or the project slug |
release | event.context.release |
exception_class | event.context.exception_class or event.context.exception.class |
transaction_name | event.context.transaction_name |
tags | event.context.tags |
context_json | The full event.context object |