A modern dashboard (TanStack Start, as of v0.3) that provides real-time insights into ClickHouse clusters through system tables. Every page is pre-rendered at build time with client-side data fetching for optimal performance and CDN caching.

Upgrading from v0.2? v0.3 rebuilds the app on TanStack Start. ClickHouse connection vars are unchanged; browser vars move from NEXT_PUBLIC_* to VITE_* (old names still work as a fallback). See Upgrading to v0.3 below or the full Migrate to v0.3 guide.

Live: dash.chmonitor.dev | chmonitor.dev | Screenshots

Features:

• Query Monitoring: Running queries, query history, resources (memory, parts read, file_open), expensive queries, slow queries, failed queries, query profiler
• Cluster Overview: Memory/CPU usage, distributed queue, global settings, MergeTree settings, metrics, asynchronous metrics
• Data Explorer: Interactive database tree browser with fast tab switching and column-level details, projections, dictionaries
• Table Analytics: Size, row count, compression, part sizes with column-level granularity, detached parts, readonly tables, view refreshes
• Visualization: 30+ metric charts for queries, resources, merges, performance, and system health
• Merge & Replication: Merge operations, merge performance, replication queue, replicas
• Security & Access: Users, roles, security settings
• Developer Tools: Zookeeper explorer, query EXPLAIN, query kill, distributed DDL queue, mutations
• Multi-Host Support: Monitor multiple ClickHouse instances from a single dashboard
• AI Agent: Built-in AI chat for natural language queries against your ClickHouse cluster
• MCP Server: Model Context Protocol endpoint for AI tool integration (Claude, Cursor, etc.)
• Rust CLI: Standalone terminal and TUI monitoring tool

This project supports deployment to Cloudflare Workers with static site generation and API routes.

Prerequisites:

• Node.js 18+ and Bun
• Cloudflare Workers account
• Wrangler CLI: npm install -g wrangler

Setup:

1. Clone and install dependencies:

git clone https://github.com/duyet/clickhouse-monitoring.git
cd clickhouse-monitoring
bun install

2. Configure environment variables in .env.local:

CLICKHOUSE_HOST=https://your-clickhouse-host.com
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=yourpassword
CLICKHOUSE_TZ=UTC

Optional API-key protection for /api/v1/* routes:

CHM_API_KEY_SECRET=your-signing-secret

Optional Clerk UI/session support:

CHM_AUTH_PROVIDER=clerk
NEXT_PUBLIC_AUTH_PROVIDER=clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_your_key
CLERK_SECRET_KEY=sk_live_your_key

Feature permissions default to enabled and public. Add sparse overrides when a deployment should hide or protect a feature:

# /etc/clickhouse-monitor/config.toml
[features.agent]
access = "authenticated"

[features.metrics]
enabled = false

access = "guest" is accepted as an alias for access = "public".

CHM_CONFIG_FILE=/etc/clickhouse-monitor/config.toml
# or env-only:
CHM_FEATURE_AGENT_ACCESS=authenticated
CHM_DISABLED_FEATURES=settings,metrics

Leave auth provider env unset or set it to none for self-hosted deployments without auth.

3. Deploy to Cloudflare Workers:

# Set CLOUDFLARE_API_TOKEN in .env.prod or export it
# OR use OAuth: npx wrangler login

# Unified deploy (config, build, deploy, cache — same as CI)
bun run cf:deploy

Manual Deployment Steps:

# Step by step (same as CI)
bun run cf:config      # Set secrets from .env.prod
bun run cf:build       # Next.js build + OpenNext
wrangler deploy --minify
opennextjs-cloudflare populateCache remote

Important Notes:

• Build uses Webpack (not Turbopack) due to Cloudflare Workers compatibility
• Next.js version pinned to 15.5.x (React 19) for stability
• Static pages are pre-rendered at edge for optimal performance
• API routes run on Workers using Fetch API
• Supports multi-host monitoring with query parameter routing (?host=0)

docker run -d \
  -p 3000:3000 \
  -e CLICKHOUSE_HOST=https://your-clickhouse-host.com \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=yourpassword \
  ghcr.io/duyet/chmonitor:latest

Tagged releases are built by GitHub Actions from tags matching v*. The release page includes:

• Docker images published to ghcr.io/duyet/chmonitor with the release version tag
• a Next.js standalone archive for Node.js deployments
• a Cloudflare Workers/OpenNext archive for manual inspection or deployment
• generated release notes with CLI command usage, Docker tags, deployment steps, and checksums

For repeatable Docker deploys, prefer the versioned image tag from the release page instead of latest.

v0.3 rebuilds the dashboard on TanStack Start. Features, routes, and ClickHouse setup carry over unchanged. The only env change is the browser variable prefix, and the old names keep working:

VITE_* vars are build-time inlined — set them when building the image/Worker, not only at runtime. Full per-platform steps: Migrate to v0.3.

Paste your current configuration (.env, docker-compose.yml, Helm values.yaml, or a k8s manifest) into any AI assistant with the prompt below. It applies the v0.3 rename rules and returns the migrated config plus a summary of what changed. This same prompt ships in every breaking-change GitHub Release and is kept in sync from .github/release-migration-prompt.md.

You are migrating a chmonitor deployment from v0.2 (Next.js) to v0.3 (TanStack Start).
Here is my current environment (.env / docker-compose / wrangler / k8s manifest):

<PASTE YOUR ENV HERE>

Rewrite it for v0.3 applying EXACTLY these rules, and output the migrated config
plus a short list of what you changed:

1. Rename every client var prefix NEXT_PUBLIC_ -> VITE_. Specifically:
   NEXT_PUBLIC_AUTH_PROVIDER          -> VITE_AUTH_PROVIDER
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY  -> VITE_CLERK_PUBLISHABLE_KEY
   NEXT_PUBLIC_FEATURE_CONVERSATION_DB-> VITE_FEATURE_CONVERSATION_DB
   (any other NEXT_PUBLIC_X -> VITE_X). The old names still work as a fallback.
2. Add server-side auth var CHM_AUTH_PROVIDER (none|clerk|proxy) mirroring the
   client provider. It is authoritative on the server; keep VITE_AUTH_PROVIDER too.
3. Do NOT rename server vars: CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD,
   CLICKHOUSE_NAME, CLICKHOUSE_MAX_EXECUTION_TIME, CLERK_SECRET_KEY, *_API_KEY — keep as-is.
4. VITE_* vars are build-time inlined: ensure they are present at image/Worker BUILD
   time (Docker build-args or CI build env), not only at container runtime.
5. If this is a Docker deployment, change the container start command from
   `node server.js` to `node server/index.mjs`. Port 3000 and the /api/healthz
   healthcheck are unchanged.
6. Flag anything that has no v0.3 equivalent instead of silently dropping it.

• /docs - Full documentation site (local/docs)
• llms.txt - AI agent discovery file for automated code understanding
• https://zread.ai/duyet/clickhouse-monitoring (AI Generated)
• https://duyet.github.io/clickhouse-monitoring
  • Getting Started
    • Local Development
    • User Role and Profile
    • Enable System Tables
  • Deployments
    • Vercel
    • Docker
    • Kubernetes Helm Chart
  • Advanced

llms.txt — standardized file that helps AI coding agents discover and understand the codebase structure. Access at https://your-domain.com/llms.txt or /llms.txt in local development.

MCP Server — exposes a Model Context Protocol endpoint at /api/mcp for AI tools to query your ClickHouse cluster directly. See docs/knowledge/mcp-server.md for setup.

Knowledge Graph — developer-facing notes in docs/knowledge/ with decisions, conventions, and architecture docs. See docs/knowledge/README.md for the index.

Feedback and contributions are welcome! Feel free to open issues or submit pull requests.

See LICENSE.