ch-ui: a ClickHouse management platform that ships as one binary

The pitch: download one binary, run it, get a workspace

CH-UI describes itself as the open-source ClickHouse management platform, with SQL editor, dashboards, AI copilot, data pipelines and ingest, telemetry, models, and admin, all in one binary. Free.

The positioning against the alternatives is direct. Most ClickHouse tools give you a query box and call it a day, whereas CH-UI gives you a full workspace, and almost everything is free and open source.

The install model is the reason this is worth looking at. No Docker requirement, no external dependencies, no signup. The binary embeds the frontend, so the deployment story is a file on a server and a port, and the Docker image is there for people who want it but nobody needs it.

The feature list is long and specific. A multi-tab SQL editor with formatting, profiling and streaming results. Dashboards with a drag-and-drop panel builder and multiple chart types. Brain, an AI assistant that understands your schema. Data pipelines with a visual builder. Ingest that receives OpenTelemetry logs and traces, JSON events, Elasticsearch bulk requests and Splunk HEC events itself, spools them on disk and writes them to ClickHouse. Telemetry search over OpenTelemetry logs in ClickHouse. Models, which are dbt-style SQL transformations with dependency graphs and scheduling. Data lineage across tables, materialized views, views and dictionaries. And an admin panel for user management, connection management and provider configuration.

The repository layout matches that scope. There is a cmd/ directory for the CLI, internal/ for the server, a ui/ directory for the Svelte frontend, a connector/ directory, an integrations/ directory, an internal license/ directory, a site/ directory, deploy/ for deployment files, and a frontend.go file at the root that is presumably the embedded asset handler. There is also a ch-ui.conf file at the root for configuration and a VERSION file.

The site is ch-ui.com, the licence is Apache 2.0 with a Business Source License overlay for the Pro features, and the release history shows v2.28.1 on 2026-10-17, v2.28.0 the same day and v2.27.0 the day before. That is a fast release cadence for a project of this size.

The SQL editor, and the features that come from knowing ClickHouse internals

The SQL editor section is where the ClickHouse-specific knowledge shows, and three of the features exist because the editor reads ClickHouse's own system tables rather than guessing.

Live query progress gives you elapsed time, percent complete, rows and bytes read, and read throughput while the query is still running, and the documentation notes it needs SELECT on system.processes. That is not a client-side timer, it is a read of the server's view of the running query.

Query cost estimation shows estimated rows and parts to scan before you run the query, compared in the documentation to BigQuery's dry run. Query profiling pulls from system.query_log and gives you an estimate versus actual accuracy comparison, which is the interesting number: it tells you how far off the optimiser's estimate was, which is a better signal about query health than the runtime alone.

The query plan analysis gives you an EXPLAIN with a parsed tree view, and streaming results come over SSE with no timeout on long queries. There are configurable limits for maximum result rows and query timeout, and query parameters in the {name:Type} bind parameter style are supported in the editor.

The editor itself is CodeMirror 6 with SQL syntax highlighting and autocomplete, with a multi-tab interface and persistent state, and query formatting and beautification.

Underneath, the whole thing is streaming from a server that knows what the query is doing, which is the difference between a query box and a client that understands the database. A generic SQL client cannot show you read throughput because it has no visibility into the server's execution.

Pipelines, and the durable webhook that survives a ClickHouse outage

The data pipelines feature is the most substantial piece of engineering in the free tier, and one line in it deserves attention.

Durable webhook: every request is written to an on-disk spool before the 200, so a ClickHouse outage or a restart loses nothing that was acknowledged.

That is a specific and deliberate design decision, and it changes what the endpoint means. A webhook receiver that returns 200 and then writes to the database has a gap between the acknowledgement and the write, and any failure in that gap is a lost event that the sender will never retry, because it already got a success. Spooling to disk before the 200 closes the gap, and it means the sender's retry logic and the receiver's durability are consistent with each other.

The rest of the pipeline system is substantial. The source connectors are Webhook, Ingest, Database, S3 and Kafka with SCRAM auth, and the transforms are Parse with JSON, logfmt, regex, nginx and Apache access logs and syslog, Map fields, and Filter, with Sample, Redact and Route as Pro. The Route transform supports up to eight sinks per pipeline. Every transform node has a preview showing records before and after the chain, dropped records with the reason, and parse errors, which is the kind of debugging view that turns a data pipeline from a black box into something you can fix.

The sink is ClickHouse, with a dead-letter table for refused rows, and there are table layouts for auto-created tables: custom from data, wide events, OpenTelemetry logs and OpenTelemetry traces.

The Ingest feature is built into the binary rather than being a separate service. The receivers are POST /ingest/v1/logs and /ingest/v1/traces for OTLP over HTTP with protobuf or JSON, /ingest/v1/events for a JSON object, array or NDJSON, /ingest/es for the Elasticsearch bulk API, and /ingest/services/collector for Splunk HEC. It works with the OpenTelemetry Collector, OTel SDKs, Vector, Fluent Bit, Filebeat, Logstash, Splunk HEC clients and plain curl.

Per-pipeline ingest keys with the chi_ prefix are stored hashed, shown once and revocable, with a per-key rate limit. Stored hashed and shown once is the right combination: the sender has the key, the server does not keep a recoverable copy, and a leak of the stored value is useless for authenticating.

Brain, the AI assistant, and what it can and cannot reach

Brain is the AI assistant, and the feature list is careful about both its reach and its limits.

It lets you chat with your data using natural language, with multi-chat support and full history persistence. The provider support is wide: Anthropic, OpenAI, OpenAI-compatible APIs including Azure, OpenRouter, Groq, Together and vLLM, and Ollama for local models. Admin-controlled model and provider activation means the choice of provider is a policy setting rather than something each user configures.

The schema-aware context is the part that makes it more than a chat box. You type @ to mention tables, dashboards, pipelines, models or saved queries in a message, so the model gets the definition of the thing you are talking about rather than a guess. SQL artifact generation lets you run the generated query directly from the chat, and Brain skills are configurable system prompts and instructions.

There are also global token budgets, per person and per role, with dollar budgets as a Pro feature. That is the right shape for a feature that costs money per use, and putting the limit at the role level rather than the user level means you can let support staff query data without giving them an unbounded budget.

The dependency list confirms the provider story. The module includes github.com/modelcontextprotocol/go-sdk, so Brain speaks the Model Context Protocol, and coreos/go-oidc for OpenID Connect, and oauth2 and crypto for the provider credentials.

The models feature, by contrast, is not an AI feature at all. Models are dbt-style SQL transformations with dependency graphs and scheduling, which is the piece of the platform that has nothing to do with a language model and everything to do with the fact that a ClickHouse installation accumulates hundreds of views and materialized views whose dependencies nobody has written down.

The licence split, and the production checklist that comes with it

The licensing is the first thing to check, because the badge spells it out: License Apache 2.0 + BSL 1.1 (Pro).

The free Community edition is everything in the free feature list, under Apache 2.0. The Pro features are under the Business Source License, which is a source-available licence rather than an open source one, and the repository carries LICENSE.BSL, LICENSE.md and a LICENSING.md alongside each other, plus an internal license/ directory in the tree.

Which features are Pro is stated inline rather than being a matter of trial and error. Sample, Redact and Route in the pipeline transforms are Pro, with Route supporting up to eight sinks per pipeline. The per-role and dollar token budgets in Brain are Pro. And the service map in Telemetry is Pro, along with traces and metrics in that area, while the OpenTelemetry log search itself is free.

The docker-compose file is a short and well-commented quick start, and its comments are the operational guidance in practice.

  ch-ui:
    image: ghcr.io/caioricciuti/ch-ui:latest
    # Or build locally: build: .
    restart: unless-stopped
    ports:
      # Bound to localhost. Publish on all interfaces only behind TLS.
      - "127.0.0.1:3488:3488"

Three things in there matter. The port is bound to localhost only, and the comment says to publish on all interfaces only behind TLS. The APP_SECRET_KEY environment variable is described as generating and persisting a random key in the data volume when empty, and setting a strong random value manages the key externally, and the reason given is that it encrypts stored credentials. And the ClickHouse service is pinned by digest, clickhouse/clickhouse-server:25.8 with a sha256, with a comment that it is the same image and digest CI tests against.

The comment about the first ClickHouse admin to sign in becoming the CH-UI admin is the sort of bootstrap rule that trips people up, and the access management detail is worth knowing: the ClickHouse user you sign in with can read system.users, and that is how CH-UI recognises it as an admin. So the account that CH-UI treats as an administrator is a ClickHouse account with read access to your user table, and giving it that access to a production instance is a decision rather than a default.

The build, the pinned toolchain, and why the Go version is spelled out to the patch

The go.mod file carries the most unusual comment in this repository, and it is about the Go version.

The patch version is spelled out on purpose. go1.26 through go1.26.5 carry four standard library vulnerabilities govulncheck reports against this code, GO-2026-6218 in net/url, GO-2026-6090 in crypto/tls, and GO-2026-6089 and GO-2026-6088 in net/http. CI's setup-go reads this line and installs exactly this toolchain, the Dockerfile's golang image matches it, and govulncheck scans with that toolchain. The instruction is to raise it to pick up stdlib fixes.

So the module is pinned to go 1.26.9 and the reasoning is spelled out: the four affected standard library versions have known vulnerabilities, so pinning to a specific patch is a security decision, and the whole toolchain chain is arranged so that the CI scan, the developer setup and the container image all agree on it.

That is stricter than most projects and it is worth copying. A go directive with a patch version is unusual, and the comment explains why it is there, so nobody helpfully rounds it down to 1.26 later.

The build itself is a two-stage affair. The frontend is a Svelte application built with Bun, and the Makefile has a build-frontend target that runs bun install with a frozen lockfile and then bun run build, with a fallback that retries with minification disabled if the frontend build was killed for memory. The Go side is built with CGO_ENABLED=0 and -trimpath and version stamping through ldflags.

The Dockerfile pins every base image by digest, the Bun image matching ui/.bun-version and the Go image matching the go directive, and the runtime is Alpine with a non-root user, a healthcheck against /health on port 3488, and the entrypoint is ch-ui server.

The test target runs the Go tests with the race detector, and the CI does the same.

Editorial conclusion

Adopt ch-ui if you run ClickHouse and want one tool for querying, dashboards, ingest and lineage rather than four separate projects, and if your team is comfortable with a platform that has a commercial tier. Do not adopt it expecting the whole feature list to be free, because Sample, Redact and Route in the pipeline transforms, the per-role token budgets and the service map are marked as Pro, and the Pro code is under BSL 1.1 rather than Apache 2.0. Before you deploy, set APP_SECRET_KEY to a strong random value because it encrypts stored credentials, and terminate TLS at a proxy or with the tls_cert_file and tls_key_file options.

Frequently asked questions

Official sources

1. caioricciuti/ch-ui on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases