ClickHouse

ClickHouse is used for Mastra observability storage when the API is configured for the ClickHouse provider.

What It Owns

Local development can run clickhouse/clickhouse-server:25.9.3.48-alpine with the observability compose profile.
apps/api uses @mastra/clickhouse for Mastra observability storage.
Observability data is traces, logs, metrics, scores, and feedback-style runtime diagnostics, not product source-of-truth data.

Architecture Decision

Decision: use ClickHouse as the high-volume observability backend through Mastra composite storage, while keeping application data on its owning stores.

Mastra docs recommend ClickHouse for production observability because insert-only trace export and columnar compression fit high-volume span/log workloads.

@mastra/clickhouse@1.9.0 creates v-next observability delta tables with TTL expressions over DateTime64(9, 'UTC') ingestion cursors. The local compose image must stay on a ClickHouse version that accepts DateTime64 TTL expressions.

How To Upgrade

Check ClickHouse release notes and Docker tag guidance for the target server version.
Update clickhouse/clickhouse-server in docker-compose.yml.
If the Mastra adapter changes, update @mastra/clickhouse with the rest of the Mastra package family:
Terminal window
```
# from apps/api
bun update @mastra/clickhouse
```

Verify API observability:

bun run --cwd apps/api check-types
bun run --cwd apps/api test:observability:clickhouse:smoke

For production/customer-hosted ClickHouse, use a runbook for backup, retention, credentials, network access, and any schema migrations.

Current Limits

ClickHouse is not the default app metadata store.
Runtime credentials should be scoped to the operations required by the observability adapter.
Do not expose sensitive prompt, provider payload, auth, or connector data in traces.

Canonical Sources

docker-compose.yml
apps/api/src/mastra/runtimeStorage.ts
apps/api/src/env.ts
apps/api/package.json
docs/features/chat/spec.md