v0.3 — What's New

Open as Markdown

v0.3 rebuilds the dashboard on TanStack Start, ships a pluggable authentication system, and delivers monitoring and UI improvements accumulated during the v0.2 cycle.

TanStack Start (new framework)

The dashboard is rewritten on TanStack Start with Vite. Every page is pre-rendered at build time so the initial shell loads from cache before ClickHouse is contacted. The legacy Next.js app is removed.

Static prerender for all 75+ dashboard pages (#1392).
TanStack Query replaces SWR for client-side data fetching (#1562).
Cloudflare Workers and Docker/Node builds from the same source — no OpenNext layer.
NEXT_PUBLIC_* env vars renamed to VITE_*; old names still work as a fallback.
Static loading skeletons for faster first paint (#1506).
Query cache persisted to localStorage for instant warm loads (#1505, #1508).
Immutable /assets/* cache headers for lower TTFB (#1507).
Background polling paused on hidden tabs (#1523).
Collapsed chart rows unmounted to stop background polling (#1580).

See Migrate to v0.3 for upgrade steps.

Pluggable authentication

A new server-side auth layer replaces the previous Clerk-only approach. Set CHM_AUTH_PROVIDER to choose how requests are authenticated (#1440):

Provider	Description
`none`	Default. Dashboard is open — no login required.
`clerk`	Clerk browser sessions — same as v0.2.
`proxy`	Trust a reverse proxy: Cloudflare Access JWT or a trusted header + shared secret.

Additional auth features:

Read/write permission model + CHM_CLERK_PUBLIC_READ for public read access (#1535, #1536).
Always-on API key layer (CHM_API_KEY_SECRET) issues signed chm_ Bearer tokens for scripts and MCP clients, independent of the active provider.
auth=none opens everything; backend still enforces per-endpoint (#1533).
Auth on /api/v1/clean, /api/v1/init, /api/v1/pageview endpoints (#1602).

See Authentication for setup details.

Cluster topology visualization

The /cluster page now shows a live topology diagram.

Shard and replica nodes drawn with distinct shapes and the ClickHouse logo.
Physical cluster groupings shown with labeled hull overlays.
Nodes sized and colored by live metrics.
Nodes can be toggled on/off; the diagram adjusts height to the data.

AI agent

The built-in AI agent runs on the Vercel AI SDK ToolLoopAgent pattern with 29+ tool categories covering schema, queries, diagnostics, cluster health, anomaly detection, capacity, replication, security, visualization, and more.

Conversation titles auto-generated from the first message.
Conversation storage — persist agent sessions to D1 (Cloudflare) or memory (#1517).
Findings — the agent records and lists persistent findings across sessions.
Workflow harness — dynamic workflow templates for multi-step analysis (incident-investigation, health-check, query-optimization, capacity-planning, replication-triage, migration-safety).
BI-style SQL Console in the explorer for ad-hoc queries (#1531).
Multi-provider LLM config (LLM_API_KEY, LLM_API_BASE, LLM_MODEL) plus a redesigned chat UI with model selector.
Hover-prefetch and lazy provider init for lower interaction latency (#1544).

MCP server

MCP endpoint at /api/mcp — Streamable HTTP, stateless, no separate worker required.
Clerk OAuth login/consent flow for MCP clients — authenticate with a browser OAuth flow instead of a chm_ key.
In-process MCP route in the TanStack app.

Query page improvements

Running queries split into a live “Running” table and a “Recently completed” table with animated row transitions.
Slow, expensive, and failed query pages redesigned with expand panels, per-column filters, and highlighted columns.
EXPLAIN tree — the Explain page renders the query plan as an interactive tree. Five explain modes (Plan, Pipeline, AST, Syntax, Estimate).
Request Info dialog redesigned with formatted SQL and metadata badges.
Menu counts batched into a single query per page load (#1591).

Table/card layout for all data pages

Every data table now has a card grid view alongside the standard table view. Toggle between them per page; cards default on narrow screens.

Rolled out across all 54 query-config pages (tables, merges, replication, system, diagnostics, keeper, and more).
Rich expandable rows for SQL, metadata, and related actions inline.
Mobile layout uses SQL-hero cards.

New monitoring views

Added from ClickHouse system tables:

Kafka consumers — system.kafka_consumers at /kafka-consumers.
Part log — system.part_log redesigned with lifecycle charts, KPIs, and a filterable events table.
Query metric log — system.query_metric_log at /query-metric-log.
User processes — system.user_processes with formatted badges and memory bars.
Moves — system.moves at /moves.
Dropped tables — system.dropped_tables at /dropped-tables.
Warnings — system.warnings at /warnings.
Replicated fetches — system.replicated_fetches at /replicated-fetches.
Replicated MergeTree settings — at /replicated-merge-tree-settings.

Deployment

Helm chart — production-ready Helm chart in deploy/helm/ alongside kustomize bases.
Health alerting — cron-based health sweep runs automatically and can post alerts to Slack or Discord.
CSV export — export any chart card’s data to CSV.
Auto-refresh interval persisted to localStorage across reloads.
Time range persisted to localStorage and synced to the URL.

Breaking changes

See Migrate to v0.3 for upgrade steps. The only required action for most self-hosters is a redeploy. The NEXT_PUBLIC_* → VITE_* rename is optional — old names still work.