docs/deployment/clickhouse.mdx
The TensorZero Gateway can optionally collect inference and feedback data for observability, optimization, evaluation, and experimentation. Under the hood, TensorZero stores this data in ClickHouse, an open-source columnar database that is optimized for analytical workloads.
<Tip>If you're planning to use the gateway without observability, you don't need to deploy ClickHouse.
You can also deploy Postgres as the backend for observability. We recommend using ClickHouse if you're handling >100 inferences per second.
</Tip>For development purposes, you can run a single-node ClickHouse instance locally (e.g. using Homebrew or Docker) or a cheap Development-tier cluster on ClickHouse Cloud.
See the ClickHouse documentation for more details on configuring your ClickHouse deployment.
For production deployments, the easiest setup is to use a managed service like <a href="https://clickhouse.com/cloud" target="_blank">ClickHouse Cloud</a>.
ClickHouse Cloud is also available through the AWS Marketplace, GCP Marketplace, and Azure Marketplace.
Other options for managed ClickHouse deployments include Tinybird (serverless) and Altinity (hands-on support).
<Note>TensorZero tests against ClickHouse Cloud's regular (recommended) and fast release channels.
You can alternatively run your own self-managed ClickHouse instance or cluster.
<Warning>We strongly recommend using ClickHouse lts instead of latest in production.
We test against both versions, but ClickHouse latest often has bugs and breaking changes.
TensorZero supports single-node and replicated deployments.
<Warning>TensorZero does not currently support sharded self-hosted ClickHouse deployments.
</Warning>See the ClickHouse documentation for more details on configuring your ClickHouse deployment.
To configure TensorZero to use ClickHouse, set the TENSORZERO_CLICKHOUSE_URL environment variable with your ClickHouse connection details.
TENSORZERO_CLICKHOUSE_URL="http[s]://[username]:[password]@[hostname]:[port]/[database]"
# Example: ClickHouse running locally
TENSORZERO_CLICKHOUSE_URL="http://chuser:chpassword@localhost:8123/tensorzero"
# Example: ClickHouse Cloud
TENSORZERO_CLICKHOUSE_URL="https://USERNAME:[email protected]:8443/tensorzero"
# Example: TensorZero Gateway running in a container, ClickHouse running on host machine
TENSORZERO_CLICKHOUSE_URL="http://host.docker.internal:8123/tensorzero"
If you're using a self-hosted replicated ClickHouse deployment, you must also provide the ClickHouse cluster name in the TENSORZERO_CLICKHOUSE_CLUSTER_NAME environment variable.
By default, the TensorZero Gateway applies ClickHouse migrations automatically when it starts up.
This behavior can be suppressed by setting observability.disable_automatic_migrations = true under the [gateway] section of config/tensorzero.toml.
See https://www.tensorzero.com/docs/gateway/configuration-reference#gateway.
If automatic migrations are disabled, then you must apply them manually with
docker run --rm -e TENSORZERO_CLICKHOUSE_URL=$TENSORZERO_CLICKHOUSE_URL tensorzero/gateway:{version} --run-clickhouse-migrations.
The gateway will error on startup if automatic migrations are disabled and any required migrations are missing.
If you're using a self-hosted replicated ClickHouse deployment, you must apply database migrations manually; they cannot be applied automatically.