chmonitorv0.3 — What's New
What's new in chmonitor v0.3 — TanStack Start framework, pluggable auth, MCP server, AI agent improvements, and new monitoring views.
v0.3 rebuilds the dashboard on TanStack Start, ships a pluggable authentication system, and delivers the monitoring and UI improvements accumulated during the v0.2 cycle.
Upgrading from v0.2?
For most self-hosters, the only required action is a redeploy. The NEXT_PUBLIC_* → VITE_* rename is optional — old names still work. See Migrate to v0.3 for the full walkthrough.
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 toVITE_*; 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_READfor public read access (#1535, #1536). - Always-on API key layer (
CHM_API_KEY_SECRET) issues signedchm_Bearer tokens for scripts and MCP clients, independent of the active provider. auth=noneopens everything; the backend still enforces per-endpoint (#1533).- Auth on
/api/v1/clean,/api/v1/init,/api/v1/pageviewendpoints (#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:
| View | System table | Route |
|---|---|---|
| Kafka consumers | system.kafka_consumers | /kafka-consumers |
| Part log | system.part_log | redesigned with lifecycle charts, KPIs, and a filterable events table |
| Query metric log | system.query_metric_log | /query-metric-log |
| User processes | system.user_processes | formatted badges and memory bars |
| Moves | system.moves | /moves |
| Dropped tables | system.dropped_tables | /dropped-tables |
| Warnings | system.warnings | /warnings |
| Replicated fetches | system.replicated_fetches | /replicated-fetches |
| Replicated MergeTree settings | — | /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
NEXT_PUBLIC_* → VITE_* rename (optional)
The NEXT_PUBLIC_* → VITE_* rename is optional — old names still work as a fallback. The only required action for most self-hosters is a redeploy.
See Migrate to v0.3 for upgrade steps.