Skip to content
caioricciuti
ch-ui
Public

About

Use CH-UI to work with your data from Click House self-hosted with a user-friendly interface. CH-UI is a modern and feature-rich user interface for ClickHouse databases. It offers an intuitive platform for querying ClickHouse databases, executing queries, and visualizing metrics about your instance.

ch-ui.com

Topics

big-databig-data-analyticsbig-data-visualizationclickhouse-ui

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity

Stars

724 stars

Watchers

3 watching

Forks

72 forks
Report repository
BranchesTags

Latest commit

 

History

582 Commits

Folders and files

Repository files navigation

CH-UI Logo

CH-UI

The open-source ClickHouse management platform.
SQL editor, dashboards, AI copilot, data pipelines and ingest, telemetry, models, and admin, all in one binary. Free.

Version License: Apache 2.0, Pro features BSL 1.1 Stars Docker

Documentation · Install · Pricing · Changelog

Why CH-UI?

Most ClickHouse tools give you a query box and call it a day. CH-UI gives you a full workspace, and almost everything is free and open source.

Download one binary. Run it. Get:

  • 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 (Anthropic, OpenAI, Ollama, or any OpenAI-compatible provider)
  • Data pipelines: visual builder for Webhook, Ingest, S3, Kafka, and DB sources into ClickHouse, with Parse, Map fields and Filter transforms
  • Ingest: CH-UI 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 OpenTelemetry logs in ClickHouse, whether your collector writes them or CH-UI received them (traces, metrics and the service map with Pro)
  • Models: dbt-style SQL transformations with dependency graphs and scheduling
  • Data lineage: how data flows between tables, materialized views, views and dictionaries
  • Admin panel: user management, connection management, provider configuration
  • Saved queries, schema explorer, connection management, and more

No Docker requirement. No external dependencies. No signup.

Table of Contents

Features (Free)

Everything below is included in the free Community edition under Apache 2.0.

SQL Editor

  • Multi-tab interface with persistent state
  • CodeMirror 6 with SQL syntax highlighting and autocomplete
  • Query formatting and beautification
  • Streaming results via SSE, no timeout on long queries
  • Live query progress: elapsed time, percent complete, rows/bytes read and read throughput while the query is still running (needs SELECT on system.processes)
  • Query cost estimation: see estimated rows and parts to scan before running (like BigQuery's dry run)
  • Query profiling (pulls from system.query_log) with estimate vs actual accuracy comparison
  • Query plan analysis (EXPLAIN with parsed tree view)
  • Configurable max result rows and query timeout
  • Query parameters ({name:Type} bind params) in the editor

Schema Explorer

  • Full database/table/column tree browser
  • Table data preview with pagination
  • Column type introspection
  • Search across databases and tables

Dashboards

  • Create unlimited dashboards
  • Drag-and-drop panel builder
  • Panel types: table, stat, gauge, time series (line, area, stacked), bar, pie, histogram, scatter, heatmap and Markdown text
  • Drilldown links: click a value to filter the dashboard, open another dashboard, open a filled-in query, or open a URL
  • Time range selector with presets (1h, 24h, 7d, 30d, custom)
  • Timezone support
  • Auto-refresh control
  • Each panel runs its own SQL query against your ClickHouse

Brain (AI Assistant)

  • Chat with your data using natural language
  • Multi-chat support with full history persistence
  • Provider support: Anthropic, OpenAI, OpenAI-compatible APIs (Azure, OpenRouter, Groq, Together, vLLM, etc.), Ollama (local LLMs)
  • Admin-controlled model and provider activation
  • Schema-aware context: type @ to mention tables, dashboards, pipelines, models or saved queries in a message
  • SQL artifact generation: run generated queries directly from chat
  • Brain skills (configurable system prompts/instructions)
  • Global token budgets (per person, per role and dollar budgets are Pro)

Data Pipelines

  • Visual pipeline canvas (drag-and-drop with XyFlow)
  • Source connectors: Webhook (inbound HTTP), Ingest (OTLP, JSON events, Elasticsearch bulk, Splunk HEC), Database (SQL query), S3, Kafka (with SCRAM auth)
  • Transforms: Parse (JSON, logfmt, regex, nginx/Apache access logs, syslog), Map fields and Filter are free; Sample, Redact and Route (up to 8 sinks per pipeline) are Pro
  • Preview on every transform node: records before and after the chain, dropped records with the reason, parse errors
  • Sink: ClickHouse, with a dead-letter table for refused rows
  • Table layouts for auto-created tables: Custom from data, Wide events (timestamp, service, level, message, trace_id, attributes), OpenTelemetry logs, OpenTelemetry traces
  • 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
  • Pipeline start/stop controls
  • Run history, metrics, and error tracking
  • Real-time monitoring (rows ingested, bytes, batches, errors, per-node counters)
  • Docs: ch-ui.com/docs/pipelines

Ingest

  • Receivers built into the binary: POST /ingest/v1/logs and /ingest/v1/traces (OTLP over HTTP, protobuf or JSON), /ingest/v1/events (JSON object, array or NDJSON), /ingest/es (Elasticsearch bulk API) and /ingest/services/collector (Splunk HEC)
  • Works with the OpenTelemetry Collector, OTel SDKs, Vector, Fluent Bit, Filebeat, Logstash, Splunk HEC clients and plain curl
  • Per-pipeline ingest keys (chi_...), stored hashed, shown once, revocable; per-key rate limit and per-pipeline daily quota
  • Requests are fsynced to a spool in <data dir>/ingest-spool before they are answered, then written to ClickHouse with a stable deduplication token
  • Logs and traces land in the OpenTelemetry exporter's table layout, so Telemetry reads them with no extra setup
  • Send data here panel in the pipeline editor fills in shipper configs with your URL and key
  • Optional separate listener (--ingest-addr :4318) for shipper traffic
  • Docs: ch-ui.com/docs/ingest

Telemetry

  • Logs explorer over OpenTelemetry data in ClickHouse: search syntax, histograms, facets, surrounding context, logs by trace
  • Sources: detect the exporter's tables or map your own; saved searches
  • Nothing copied or indexed elsewhere, every screen is SQL against your tables
  • Pro: Traces, Metrics, Service map and Monitors
  • Docs: ch-ui.com/docs/telemetry

Models (SQL Transformations)

  • dbt-style SQL models with table, view, and incremental materialization
  • Model dependency graph (DAG visualization)
  • Execution with dependency ordering
  • Run history and results tracking
  • Table engine configuration per model
  • Run manually or on a cron schedule (model and pipeline schedules are free)

Data Lineage

  • See how data flows between tables, materialized views, views, dictionaries and external sources (Kafka, S3, URL, MySQL and table functions)
  • Explore › Lineage with database picker, focus search, 1 to 4 hops and kind filters; a Lineage view on every table page
  • Read on demand with your own ClickHouse account from system tables, cached for 30 seconds, never reads query_log
  • Docs: ch-ui.com/docs/lineage

Saved Queries

  • Save queries with titles and descriptions
  • Sort by date, name, or query length
  • Filter, search, copy, and organize
  • Quick access from the sidebar

Admin Panel

  • User management (create, delete, assign roles)
  • ClickHouse user management (create users, update passwords, delete)
  • Connection management with multi-connection support
  • Brain provider and model configuration
  • Brain skill management
  • System statistics dashboard

Connections & Tunnel

  • Multi-connection support (manage multiple ClickHouse instances)
  • Secure WebSocket tunnel for remote ClickHouse access
  • Token-based agent authentication
  • Connection health monitoring
  • Install connector as OS service (ch-ui service install, Linux and macOS)

MCP Server

  • Embedded Model Context Protocol server at /mcp (streamable HTTP), in the same binary
  • Connect Claude Code, claude.ai, ChatGPT, Cursor or VS Code with OAuth sign-in or a revocable chm_ key
  • Read tools by default: schema browsing, SELECT queries, saved queries, query plans, telemetry logs, lineage, model and pipeline status
  • Opt-in permissions: write (saved queries, dashboards, draft models and pipelines) and lifecycle actions (run models, start and stop pipelines), each confirmed in the client when it supports prompts
  • Server-side enforcement (readonly, row/time caps, database allowlist) + every AI call recorded in the audit log
  • Pro: alerts, schedules, reports, cluster health, Query Insights, Cost Center, traces and metrics tools, and running schedules and reports now
  • Docs: ch-ui.com/docs/mcp

Other

  • Dark mode
  • Session-based authentication with rate limiting
  • Security headers (CSP, X-Frame-Options, etc.)
  • Health check endpoint (/health)
  • Self-update (ch-ui update)
  • Personal desktop mode (ch-ui desktop): loopback only, data in your user folder, opens the browser
  • Binaries for Linux, macOS and Windows (amd64 and arm64)
  • Shell completion generation

Community vs Pro

Almost everything is free. Pro adds production operations, governance and scheduling.

Capability Community (Free) Pro
SQL editor + explorer + formatting + profiling Yes Yes
Saved queries Yes Yes
Dashboards + panel builder Yes Yes
Brain (AI chat, multi-provider; Ask AI and agentic tools are Pro) Yes Yes
Data pipelines (Webhook, Ingest, S3, Kafka, DB) Yes Yes
Ingest receivers (OTLP logs and traces, JSON events, Elasticsearch bulk, Splunk HEC), ingest keys, durable spool Yes Yes
Pipeline transforms Parse, Map fields, Filter, with preview Yes Yes
Table layouts (Custom, Wide events, OpenTelemetry logs and traces) Yes Yes
Models (SQL transformations, DAG, cron schedules) Yes Yes
Admin panel + user management Yes Yes
Multi-connection management Yes Yes
Data lineage Yes Yes
Desktop mode (ch-ui desktop) and Linux, macOS, Windows binaries Yes Yes
Tunnel (remote ClickHouse) Yes Yes
Query parameters in the editor ({name:Type} bind params) Yes Yes
Telemetry Logs, Sources, saved searches Yes Yes
MCP server (read tools, write tools, lifecycle actions, OAuth, API keys) Yes Yes
Pipeline Sample, Redact and Route (up to 8 sinks per pipeline) - Yes
Scheduled query jobs + cron + history + parameterized saved-query runs - Yes
Scheduled reports (saved query results and dashboard summaries to email, Slack, Teams, webhooks) - Yes
Governance (metadata catalog, access matrix, policies, incidents, query audit, audit log viewer) - Yes
Policies + incidents + violations - Yes
ClickHouse access control editor, access history and drift - Yes
Access as code (export/import roles, grants, policies, quotas, profiles; create users on import) - Yes
Guardrails (query blocking in the editor and MCP) - Yes
Cluster Health (replication, Keeper, merges/mutations, parts pressure, long queries) - Yes
Query Insights - Yes
Cost Center - Yes
Performance regressions + saved before/after investigations - Yes
Fleet overview across connections - Yes
Incident timeline + deployment annotations - Yes
Schema comparison + downloadable SQL review plans - Yes
Weekly operations reports + configured email delivery - Yes
Alerting (SMTP, Slack, Teams, webhooks), incl. ingest and pipeline alerts - Yes
Telemetry Traces, Metrics, Service map, Monitors - Yes
Ask AI (text-to-SQL in the editor) + Brain agentic tools - Yes
Brain budgets per person and per role, dollar limits - Yes
GitHub sync for models - Yes
SSO (OIDC) with per-person roles and attribution - Yes
Audit forwarding to a SIEM (webhook, file, stdout) - Yes
MCP Pro tools (operations, Query Insights, Cost Center, traces and metrics, schedule and report actions) - Yes
Command palette Pro search (entity search, scope prefixes) - Yes

See: ch-ui.com/docs/license

Pipelines with Sample, Redact or Route nodes save on any edition; running or previewing them without Pro fails with 402 and names the node.

For the performance, fleet, schema comparison and weekly report workflows, see ch-ui.com/docs/performance.

Quick Start

1) Download

Linux (amd64):

curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-amd64
chmod +x ch-ui

Linux (arm64):

curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-arm64
chmod +x ch-ui

macOS (Apple Silicon):

curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-arm64
chmod +x ch-ui

macOS (Intel):

curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-amd64
chmod +x ch-ui

Windows (PowerShell):

# x64
Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-amd64.exe

# ARM
Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-arm64.exe

The Windows binary is not code signed, so SmartScreen may warn the first time you run it. Compare Get-FileHash ch-ui.exe -Algorithm SHA256 with the matching line in checksums.txt.

Optional: verify checksum (Linux, macOS):

curl -L -o checksums.txt https://github.com/caioricciuti/ch-ui/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing

2) Run

sudo install -m 755 ch-ui /usr/local/bin/ch-ui
ch-ui

Or just ./ch-ui from the download folder.

Open http://localhost:3488 and log in with your ClickHouse credentials.

On Windows, double-click ch-ui.exe (or run .\ch-ui.exe): with no arguments it starts desktop mode and opens your browser. Close its console window to stop it. Run .\ch-ui.exe server for a team server.

Just for yourself: desktop mode

ch-ui desktop

Listens on 127.0.0.1 only, keeps the database and secret key in your user data folder (~/Library/Application Support/ch-ui on macOS, %AppData%\ch-ui on Windows, $XDG_CONFIG_HOME/ch-ui or ~/.config/ch-ui on Linux), uses port 3488 or any free port, and opens your browser. Running it again opens the instance already running. See ch-ui.com/docs/installation.

Quick Start (Docker)

docker run --rm \
  -p 3488:3488 \
  -v ch-ui-data:/app/data \
  -e CLICKHOUSE_URL=http://host.docker.internal:8123 \
  ghcr.io/caioricciuti/ch-ui:latest
  • On Linux, replace host.docker.internal with a host/IP reachable from the container.
  • Persisted state is stored in /app/data/ch-ui.db (volume: ch-ui-data).

Architecture

CH-UI ships as a single binary with three operating modes:

  • server: web app + API + WebSocket tunnel gateway + ingest receivers (default on Linux and macOS)
  • desktop: the same app for one person, on 127.0.0.1 only (default on Windows)
  • connect: lightweight agent that exposes local ClickHouse over secure WebSocket
flowchart LR
    U["Browser"] --> S["CH-UI Server\n(UI + API + Gateway)"]
    SH["Shippers\n(OTel, Vector, Fluent Bit, ...)"] -->|"/ingest"| S
    S <--> DB["SQLite + ingest spool\n(state, settings, chats, dashboards)"]
    A["ch-ui connect\n(Agent)"] <--> S
    A --> CH["ClickHouse"]
Loading

For local use, the server starts an embedded connector automatically against localhost:8123.

Tech stack: Go backend (chi v5, SQLite WAL mode), Svelte 5 frontend (TypeScript, Vite, TailwindCSS), embedded at build time.

Remote ClickHouse (Tunnel)

Connect to ClickHouse instances running on other machines using the secure WebSocket tunnel.

Server (VM2):

ch-ui server --port 3488

Agent (VM1, where ClickHouse runs):

ch-ui connect --url wss://your-ch-ui-domain/connect --key cht_your_tunnel_token

Tunnel key management

Run these on the server host:

ch-ui tunnel create --name "vm1-clickhouse"   # Create connection + key
ch-ui tunnel list                              # List all connections
ch-ui tunnel show <connection-id>              # Show token + setup commands
ch-ui tunnel rotate <connection-id>            # Rotate token (old one invalidated)
ch-ui tunnel delete <connection-id>            # Delete connection
  • Token can also be generated from the Admin UI.
  • Agent only needs outbound access to the server's /connect endpoint.
  • Add --takeover to replace a stale agent session.
  • Install as OS service: ch-ui service install --key cht_xxx --url wss://host/connect

For full hardening guide: ch-ui.com/docs/deployment

CLI Reference

Quick start commands

ch-ui                        # Start server (local ClickHouse); desktop mode on Windows
ch-ui desktop                # Run for yourself on 127.0.0.1 and open the browser
ch-ui server start --detach  # Start in background
ch-ui server status          # Check if running
ch-ui server stop            # Stop server

Full command map

Command Description
ch-ui / ch-ui server Start web app + API + gateway + ingest receivers (ch-ui alone runs desktop on Windows)
ch-ui desktop Run CH-UI for yourself on this computer, loopback only, and open the browser
ch-ui connect Start tunnel agent next to ClickHouse
ch-ui tunnel create/list/show/rotate/delete Manage tunnel keys (server host)
ch-ui server start/stop/status/restart Run the server in the background and manage it through its PID file
ch-ui service install/start/stop/restart/status/logs/uninstall Manage connector as OS service (Linux and macOS; not supported on Windows yet)
ch-ui backup [file] Consistent snapshot of the SQLite database
ch-ui reset-admin [--user <name>] [--connection <id-or-name>] Recover the CH-UI admin role when no admin can sign in
ch-ui update Update to latest release (restarts a running server; --pid-file, --stop-timeout, --restart-server)
ch-ui version Print version
ch-ui completion bash/zsh/fish/powershell Generate shell completions
ch-ui uninstall Remove CH-UI from system (stops a running desktop, keeps its data folder; --print-only to preview)

Server flags

Flag Default Description
--port, -p 3488 HTTP port
--clickhouse-url http://localhost:8123 Local ClickHouse URL
--connection-name Local ClickHouse Display name for local connection
--config, -c - Path to server.yaml
--detach - Run in background
--dev - Development mode (proxy to Vite)
--allow-login-url off Let the login page sign in with a typed ClickHouse URL. The server makes the connection, so enable only on trusted networks
--trusted-proxies loopback, private and link-local ranges Comma-separated IPs or CIDRs of reverse proxies whose X-Forwarded-For is trusted; none trusts no proxy
--ingest-addr off Also serve the /ingest receivers (and /v1 OTLP aliases) on this address, e.g. :4318
--pid-file ch-ui-server.pid Path to server PID file
--stop-timeout 10s Graceful stop timeout

ch-ui server restart runs in the background by default (--detach=false to stay in the foreground).

Desktop flags

Flag Default Description
--port, -p 3488 Port; if the default is taken, any free port is used. An explicit port fails when taken
--host 127.0.0.1 Loopback address (127.0.0.1, ::1 or localhost)
--no-browser - Do not open the browser
--clickhouse-url http://localhost:8123 Local ClickHouse URL
--connection-name Local ClickHouse Display name for local connection
--config, -c - Path to server.yaml

DATABASE_PATH and APP_SECRET_KEY override the database and key as they do for ch-ui server.

Connect flags

Flag Default Description
--url ws://127.0.0.1:3488/connect WebSocket tunnel URL (ws:// or wss://); falls back to TUNNEL_URL, then the config file
--key - Tunnel token (cht_...)
--clickhouse-url http://localhost:8123 Local ClickHouse
--config, -c - Path to config.yaml
--detach - Run in background
--takeover - Replace stale agent session

Configuration

CH-UI works without config files. You only need them for production defaults or service-managed startup.

Config file locations

File macOS Linux Windows
server.yaml ~/.config/ch-ui/server.yaml /etc/ch-ui/server.yaml pass --config
config.yaml ~/.config/ch-ui/config.yaml /etc/ch-ui/config.yaml %AppData%\ch-ui\connect\config.yaml

Priority: CLI flags > environment variables > config file > built-in defaults

Server config

port: 3488
app_url: https://ch-ui.yourcompany.com
database_path: /var/lib/ch-ui/ch-ui.db
clickhouse_url: http://localhost:8123
connection_name: Local ClickHouse
app_secret_key: "change-this-in-production"
allowed_origins:
  - https://ch-ui.yourcompany.com
Key Env var Default Description
port PORT 3488 HTTP port
app_url APP_URL http://localhost:<port> Public URL for links and tunnel inference
database_path DATABASE_PATH ./data/ch-ui.db SQLite database location
clickhouse_url CLICKHOUSE_URL http://localhost:8123 Embedded local connection target
connection_name CONNECTION_NAME Local ClickHouse Display name for local connection
app_secret_key APP_SECRET_KEY auto-generated Encrypts sessions and stored credentials. When not set, a random key is generated and persisted to .app_secret_key next to the database
app_secret_key_previous APP_SECRET_KEY_PREVIOUS empty The key in use before a rotation. Stored secrets decrypt with it as a fallback, and startup re-encrypts them with the current key
allowed_origins ALLOWED_ORIGINS empty CORS allowlist (comma-separated in env)
tunnel_url TUNNEL_URL derived from port Tunnel endpoint advertised to agents
session_max_age SESSION_MAX_AGE 604800 (7 days) Session lifetime in seconds
allow_login_url ALLOW_LOGIN_URL false Same as --allow-login-url
trusted_proxies TRUSTED_PROXIES loopback, private and link-local ranges Same as --trusted-proxies (list in YAML, comma-separated in env)
tls_cert_file / tls_key_file TLS_CERT_FILE / TLS_KEY_FILE empty Set both to serve HTTPS directly; otherwise put a TLS-terminating proxy in front
export_max_bytes / export_max_rows EXPORT_MAX_BYTES / EXPORT_MAX_ROWS 1 GiB / 10,000,000 Caps on one full result export
ingest_addr INGEST_ADDR off Same as --ingest-addr
ingest_only_separate INGEST_ONLY_SEPARATE false With ingest_addr set, stop serving /ingest on the main port
ingest_spool_max_bytes INGEST_SPOOL_MAX_BYTES 2 GiB Cap on the on-disk ingest spool (<data dir>/ingest-spool), shared by ingest and webhook pipelines. When full, the receivers answer 503
oidc_accept_unverified_email OIDC_ACCEPT_UNVERIFIED_EMAIL false Accept SSO ID tokens without an email_verified claim (some identity providers, such as Microsoft Entra ID, never send it). An explicit false claim is always refused
oidc_sso_only OIDC_SSO_ONLY false Turn off ClickHouse username/password sign-in while SSO is up, also over SSO configured in the Admin page. Break-glass: CHUI_ALLOW_PASSWORD_LOGIN=true (env only) allows it again

Audit forwarding (audit_*), the rest of SSO (oidc_*) and the Pro license (CHUI_LICENSE, CHUI_LICENSE_FILE) have their own keys. The full list is in ch-ui.com/docs/configuration.

Connector config

tunnel_token: "cht_your_token"
clickhouse_url: "http://127.0.0.1:8123"
tunnel_url: "wss://your-ch-ui-domain/connect"
Key Env var Default Description
tunnel_token TUNNEL_TOKEN required Auth key from ch-ui tunnel create
clickhouse_url CLICKHOUSE_URL http://localhost:8123 Local ClickHouse
tunnel_url TUNNEL_URL ws://127.0.0.1:3488/connect Server gateway endpoint

Changing the local ClickHouse URL

# CLI flag
ch-ui server --clickhouse-url http://127.0.0.1:8123

# Environment variable
CLICKHOUSE_URL=http://127.0.0.1:8123 ch-ui server

# With custom connection name
ch-ui server --clickhouse-url http://127.0.0.1:8123 --connection-name "My ClickHouse"

The login page also has a Can't login? button that shows setup guidance.

CH-UI can connect to ClickHouse either directly (point CLICKHOUSE_URL at the endpoint, including a reverse-proxied https:// one) or via an outbound tunnel that keeps ClickHouse fully private. See ch-ui.com/docs/connections.

Production Checklist

  • Set a strong APP_SECRET_KEY
  • Set APP_URL to your public HTTPS URL
  • Configure ALLOWED_ORIGINS
  • Put CH-UI behind a TLS reverse proxy (Nginx example: ch-ui.conf)
  • Ensure WebSocket upgrade support for /connect
  • If shippers send data to CH-UI, consider a separate ingest port (INGEST_ADDR=:4318, INGEST_ONLY_SEPARATE=true) and size INGEST_SPOOL_MAX_BYTES for the disk
  • Back up the SQLite database regularly with ch-ui backup, and keep APP_SECRET_KEY safe
  • Run connector as OS service on remote hosts

Backup and restore

# Backup: consistent snapshot, safe while the server is running
ch-ui backup /var/backups/ch-ui-$(date +%F).db -c /etc/ch-ui/server.yaml

# Restore: stop the server, replace the DB file with the backup, start it
# again with the same APP_SECRET_KEY

Do not cp the live database: it runs in WAL mode and a plain copy can be inconsistent. The backup holds credentials encrypted with APP_SECRET_KEY, so back up that key too (or the .app_secret_key file next to the database when the key was auto-generated). A backup is useless without it.

Troubleshooting

Port already in use

ch-ui server status   # Check if already running
ch-ui server stop     # Stop the old process

Can't log in

  • Authentication failed: wrong ClickHouse credentials
  • Connection unavailable: wrong URL or connector offline
  • Too many attempts: wait for retry window; fix URL first if needed

Click Can't login? on the login page for guided recovery, or restart with:

ch-ui server --clickhouse-url 'http://127.0.0.1:8123'

Full guide: ch-ui.com/docs/cant-login

Connector auth fails (invalid token)

  • Verify you copied the latest cht_... token
  • Check with ch-ui tunnel list
  • Rotate with ch-ui tunnel rotate <connection-id>

WebSocket fails behind proxy

Your proxy must forward upgrades on /connect:

  • Upgrade and Connection: upgrade headers
  • Long read/send timeouts
  • Buffering disabled for tunnel path

Health check

curl http://localhost:3488/health

Development

Requirements: Go 1.26.10+ (the version in go.mod), Bun

git clone https://github.com/caioricciuti/ch-ui.git
cd ch-ui
make build    # Full production build (frontend + Go binary)
./ch-ui

Dev mode (two terminals):

make dev                              # Terminal 1: Go server
cd ui && bun install && bun run dev   # Terminal 2: Vite dev server

Useful targets: make build | make test | make vet | make clean | make rebuild

Upgrade

ch-ui update

Downloads the latest release for your OS/arch, verifies checksum, and replaces the binary (on Windows, the running .exe too). A running server is restarted. Back up first with ch-ui backup; see ch-ui.com/docs/upgrade.

Legal

CH-UI is dual-licensed:

Contributing

Bug reports and pull requests are welcome. Bugs go in issues, questions in Discussions. Pull requests need a signed Contributor License Agreement; a bot asks on your first one. See CONTRIBUTING.md for the details.

About

Use CH-UI to work with your data from Click House self-hosted with a user-friendly interface. CH-UI is a modern and feature-rich user interface for ClickHouse databases. It offers an intuitive platform for querying ClickHouse databases, executing queries, and visualizing metrics about your instance.

ch-ui.com

Topics

big-databig-data-analyticsbig-data-visualizationclickhouse-ui

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity

Stars

724 stars

Watchers

3 watching

Forks

72 forks
Report repository

Releases

Packages

Used by

Contributors

Languages