---
title: "ClickHouse for self-hosted Langfuse: sizing and operations"
description: "How to run ClickHouse for self-hosted Langfuse: deployment options, minimum sizing, versions, disk growth, system log tables, retention, backups, and read isolation."
tags: [guide]
---

# ClickHouse for self-hosted Langfuse: sizing and operations

ClickHouse stores the traces, observations, and scores in Langfuse, and it is the component self-hosters spend the most operations time on. Most of that time goes to a short list of problems that show up in a predictable order: picking a deployment, getting the version right, then disk growth. This guide covers each one and links to the configuration reference.

**Start with Langfuse** [Sign up](/cloud)

**TL;DR:** Use ClickHouse Cloud or BYOC for larger deployments, or the official ClickHouse Kubernetes Operator if you run ClickHouse yourself. Langfuse v4 needs ClickHouse 25.12 or later, and you should run a release that still gets security patches. Start with at least 2 CPUs and 8 GiB of memory. Most disk problems come from missing retention and from ClickHouse system log tables, which have no TTL by default and which Langfuse never reads.

**Deployment architecture — your infrastructure (VPC / on-premises)**

UI, API, and SDK clients send requests to [Langfuse Web](/self-hosting/deployment/infrastructure/containers) (`langfuse/langfuse`), which serves the UI and APIs. [Langfuse Worker](/self-hosting/deployment/infrastructure/containers) (`langfuse/worker`) processes events asynchronously.

| Storage service | Purpose | Connections |
| --- | --- | --- |
| [PostgreSQL](/self-hosting/deployment/infrastructure/postgres) | Transactional data | Web → PostgreSQL; Worker → PostgreSQL |
| [Redis / Valkey](/self-hosting/deployment/infrastructure/cache) | Cache and job queue | Web → Redis / Valkey; Redis / Valkey → Worker |
| [ClickHouse](/self-hosting/deployment/infrastructure/clickhouse) | Observability data | Web → ClickHouse; Worker → ClickHouse |
| [S3 / Blob storage](/self-hosting/deployment/infrastructure/blobstorage) | Raw events and multi-modal attachments | Web → S3 / Blob storage; Worker → S3 / Blob storage |

Both containers can optionally connect to [LLM providers](/self-hosting/deployment/infrastructure/llm-api): Web for the playground, Worker for evaluations. Bring your own LLM API; it can also run in the same VPC or a peered VPC.

The optional [Langfuse AI Gateway](/self-hosting/configuration/ai-gateway) (`langfuse/ai-gateway`, beta) receives model requests from apps and coding agents. Gateway → Web resolves gateway API keys and uploads traces; Gateway → LLM providers relays the requests.

## Choose a deployment [#deployment]

| Option                             | Support level | Good for                                                                       |
| ---------------------------------- | ------------- | ------------------------------------------------------------------------------ |
| ClickHouse Cloud                   | Official      | Most production deployments; managed scaling and backups                       |
| ClickHouse BYOC                    | Official      | Managed ClickHouse with the data plane in your own cloud account               |
| ClickHouse Kubernetes Operator     | Official      | Running ClickHouse yourself on Kubernetes, with upgrades and high availability |
| Bundled in the Langfuse Helm chart | Community     | Getting started on Kubernetes; uses the operator from chart `v2.0.0`           |
| Single Docker container            | Community     | Local development only                                                         |

ClickHouse Cloud and BYOC separate storage from compute, so storage can grow without resizing compute, and they support separate compute groups for reads and writes. Self-managed ClickHouse means you own disk expansion, replicas, and merge behavior. See [ClickHouse deployment options](/self-hosting/deployment/infrastructure/clickhouse#support).

## Get the version right [#versions]

Each Langfuse major release sets a minimum ClickHouse version: 25.12 for v4 and 24.3 for v3, as of November 2026. Minor and patch releases of Langfuse never raise it.

  The minimum version is a compatibility guarantee, not a security
  recommendation. ClickHouse patches only its recent releases, so pick a
  version the [ClickHouse security
  policy](https://github.com/ClickHouse/ClickHouse/security/policy) lists as
  supported, such as the latest LTS. See [supported
  versions](/self-hosting/deployment/infrastructure/clickhouse#supported-versions).

## Size it [#sizing]

Start at the [minimum](/self-hosting/configuration/scaling#minimum-infrastructure-requirements) of 2 CPUs and 8 GiB of memory, and grow from measurements. Trace volume depends on how many observations each trace contains and how large inputs and outputs are, not on request count. A single ClickHouse shard can hold multiple terabytes of tracing data before horizontal scaling becomes a question.

Signs you need more:

- **Slow dashboards or API reads during ingestion peaks.** On ClickHouse Cloud or BYOC, route reads to a separate compute group with [`CLICKHOUSE_READ_ONLY_URL`](/self-hosting/configuration/scaling#clickhouse-read-only-url).
- **Ingestion backlog in the worker.** Scale the worker containers first, see [ingestion throughput](/self-hosting/configuration/scaling).
- **Steady disk growth.** See the next section.

## Keep disk usage under control [#disk]

Three settings cover most disk problems:

1. **Data retention.** A [data retention](/docs/administration/data-retention) policy per project deletes old traces in ClickHouse and blob storage consistently. It needs an Enterprise license on self-hosted deployments. Without it, ClickHouse [TTL](/self-hosting/configuration/scaling) on the tracing tables is the alternative.
2. **System log tables.** Tables such as `trace_log`, `text_log`, and `metric_log` have no TTL by default and can use more disk than your traces. Langfuse doesn't read them, so disable or cap them. See [ClickHouse system log tables](/self-hosting/configuration/scaling#clickhouse-system-log-tables).
3. **Lightweight deletes.** On ClickHouse 25.7 and later, lightweight deletes and updates reduce background merge work on deletion-heavy workloads. See [slow or timing-out deletions](/self-hosting/configuration/scaling#clickhouse-deletion-timeouts).

## Back it up [#backups]

ClickHouse Cloud and BYOC back up automatically. For self-managed ClickHouse, use volume snapshots or a backup tool on Kubernetes, and test restores. See [backup strategies](/self-hosting/configuration/backups). Langfuse also writes incoming events to blob storage first, which helps if ClickHouse is briefly unavailable.

## Other things to configure [#configuration]

- **Timezone:** ClickHouse must run in UTC. See [timezones](/self-hosting/deployment/infrastructure/clickhouse#timezones).
- **User permissions:** the Langfuse user needs specific grants, including on system tables. See [user permissions](/self-hosting/deployment/infrastructure/clickhouse#user-permissions).
- **Encryption at rest:** use encrypted disks or blob storage as a disk. See [ClickHouse encryption](/self-hosting/deployment/infrastructure/clickhouse).
- **Direct access:** you can query Langfuse tables for custom tools, but don't change the schema. See [direct ClickHouse access](/self-hosting/deployment/infrastructure/clickhouse#direct-clickhouse-access).

For how Langfuse Cloud runs ClickHouse at scale, see [How Langfuse runs ClickHouse at agent scale](/resources/engineering/clickhouse-at-agent-scale).

## FAQ

### Why does Langfuse need ClickHouse? [#why-clickhouse]

Traces are large, append-heavy, and queried with aggregations across millions of rows. ClickHouse stores them in columns and aggregates them quickly, which Postgres alone can't do at that volume. Postgres still stores transactional data such as users, projects, and prompts.

### Can I use another managed ClickHouse service? [#other-managed-clickhouse]

Yes, as a community-supported option. It needs to meet the minimum version, support the required settings and grants, and run in UTC.

### ClickHouse disk is filling up. What should I check first? [#disk-full]

Run the query on the [scaling page](/self-hosting/configuration/scaling) to list the largest tables. If system log tables are near the top, disable or cap them. If tracing tables are, set a retention policy or a TTL.

[Ask another question](/docs/ask-ai)

**Start with Langfuse** [Sign up](/cloud)

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/resources/engineering/clickhouse-for-self-hosted-langfuse.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx @langfuse/cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.
