v0.2.0

[0.2.0]

🏗️ Major Architecture Changes

Static Site + SWR Migration

• Migrated from SSR/dynamic routes to fully static site with client-side API routes

  • Changed routing from /[host]/overview to /overview?host=0 for better CDN caching
  • All pages are now static pre-rendered and served from edge
  • Client-side data fetching with SWR for real-time data updates
  • Benefits: Faster initial page load, better CDN distribution, simpler deployment

• Data Fetching Pattern Overhaul

  • Centralized data fetching through /api/v1/* API routes
  • All client components now use SWR hooks (useChartData, useTableData)
  • fetchData() now requires explicit hostId parameter (breaking change)
  • Introduced useHostId() hook to extract host from query parameters
  • Enables independent data refresh on host switching without full page reload

Framework & Build Updates

• Next.js 16 with React 19 and Turbopack
• Migrated to Bun as the primary package manager
  • Better performance and compatibility with modern JavaScript ecosystem
  • Replaced PNPM with Bun (bun install, bun run dev, etc.)
• Biome for code formatting and linting (replacing ESLint/Prettier)
• Bun test runner replacing Jest for unit tests
  • Faster test execution and better Node.js compatibility
  • Note: Jest was experiencing hanging issues - Bun provides a stable alternative

Cloudflare Workers Deployment

• Full support for Cloudflare Workers deployment
  • Uses OpenNextJS for Next.js compatibility
  • API routes run on Workers using Fetch API
  • Hybrid static + API architecture
  • Deploy with: bun run cf:deploy
• Enhanced CI/CD with Docker tagging strategy
  • Release workflows with automatic Docker image versioning
  • Cloudflare deployment summaries in CI output

✨ New Features

UI/UX Enhancements

• User Settings Modal: Timezone and theme management per user
• Settings Page: Column ordering with drag-and-drop, context-aware help
• Dark Mode Improvements: Fixed ClickHouse logo visibility in dark mode
• Command Palette: Keyboard shortcuts for navigation
• Readonly Tables Warning: Indicator for replica tables in cluster overview

Data Explorer & Analytics

• Page Views Analytics: 4 new charts for usage insights (browsers, devices, pages, referrers)
• Part Info Page: Detailed information about ClickHouse table parts
• Improved Table Validation: Graceful handling of optional system tables (backup_log, error_log, zookeeper)

Developer Tools

• Enhanced Query EXPLAIN: Better visualization and context
• Query Kill Functionality: Kill long-running queries from UI
• Zookeeper Explorer: Monitor cluster coordination

🚀 Performance & Infrastructure

CDN & Caching

• Static site architecture enables aggressive CDN caching at edge
• Query parameters routing improves cache hit rates
• Cloudflare Workers deployment pre-renders static pages at edge
• Supports multiple ClickHouse hosts without cache invalidation

Database Query Optimization

• Version-aware queries using chronological sql arrays
  • Handle ClickHouse schema changes across versions (v23.8, v24.1, etc.)
  • Graceful degradation for missing columns/tables
• Table validation system with 5-minute caching
  • Prevents errors on optional tables
  • User-friendly error messages

Chart & Visualization

• 30+ metric charts across all pages
• Replaced donut charts with progress bars for better readability
• Heat maps for visual performance analysis
• Graceful error handling during SWR revalidation preserves user experience

🛠️ Development & Testing

Testing Infrastructure

• Cypress component tests for UI validation
• Cypress E2E tests for user workflows
• Bun test runner for unit and integration tests
  • bun run test - Run all tests with coverage
  • bun run test:unit - Unit tests only
  • bun run test:query-config - ClickHouse query config validation
• Query Config Validation: Automated testing against multiple ClickHouse versions

Code Quality

• Biome for consistent formatting and linting
• Type safety with TypeScript 5
• React Compiler for automatic performance optimizations
• Husky + lint-staged for pre-commit checks

CI/CD Pipeline

• GitHub Actions workflows for automated testing and deployment
• Claude Code integration for AI-assisted code review
• Multi-stage Docker builds for optimized container images
• Cloudflare Workers deployment with automatic URL generation

🔄 Breaking Changes

1. Routing: /[host]/overview → /overview?host=0

   • Update bookmarks and API clients to use query parameter format

2. API - fetchData() now requires hostId:

   // Old
   const data = await fetchData(query, variables)
   
   // New - hostId is required, not optional
   const data = await fetchData(query, variables, hostId)

3. Component Props: All chart/table components require hostId prop

   • <MyChart hostId={hostId} /> instead of relying on context
   • Prevents prop drilling through explicit prop passing at usage site

4. Package Manager: Requires Bun 10.18.2+

   • bun install instead of npm install
   • bun run dev instead of npm run dev

📦 Dependencies

Major Upgrades

• React: 18 → 19
• Next.js: 13 → 15
• Tailwind CSS: 3 → 4
• TypeScript: 4 → 5
• Radix UI: Updated to latest versions with new primitives

New Dependencies

• @dnd-kit/* - Drag-and-drop functionality for column reordering
• @xyflow/react - Zookeeper explorer visualization
• opennextjs-cloudflare - Next.js on Cloudflare Workers
• biome - Code formatter and linter
• sonner - Toast notifications

🐛 Bug Fixes

• Fixed host switcher not triggering data refresh on navigation
• Fixed darkmode logo visibility issues
• Fixed cluster routing badge counts
• Fixed E2E test navigation with /tables redirect
• Fixed mock import order for Bun test runner
• Improved error handling in env-utils for client components

📊 Monitoring & Observability

• Query Performance Monitoring: Enhanced query detail page
• Cluster Health Metrics: Expanded system metrics coverage
• Error Logging: Better error context and user-friendly messages
• Table Validation: Prevents confusing errors from optional tables

📝 Documentation

• Migration Guide: From v0.1 dynamic routing to v0.2 static routing
• Cloudflare Workers Deployment: Complete setup and configuration guide
• Schema Documentation: Per-version ClickHouse schema compatibility
• Development Conventions: Code organization, patterns, and best practices
• AI Generated Docs: Available at zread.ai/duyet/clickhouse-monitoring

🎯 Comparison: v0.1.16 → v0.2.0

Aspect	v0.1.16	v0.2.0
Architecture	SSR + Dynamic Routes	Static Site + SWR API
Routing	/[host]/overview	/overview?host=0
Build Tool	Turbopack	Turbopack (same, optimized)
Framework	React 18 + Next.js 13	React 19 + Next.js 15
Package Manager	PNPM	Bun
Linting	ESLint + Prettier	Biome
Testing	Jest (with issues)	Bun test runner + Cypress
Deployment	Vercel + Docker	Vercel + Docker + Cloudflare Workers
Pages	~12 static pages	~15+ static pages + analytics
Charts	~20 charts	~30+ charts
CDN Caching	Limited (dynamic routes)	Aggressive (static pages)
Load Time	~2-3s	~0.5-1s (edge cache)

⚠️ Known Issues & Limitations

• Jest Test Runner: Currently hangs indefinitely in CI environment

  • Workaround: Using Bun test runner instead
  • Alternative: Cypress for testing until resolved

• Cloudflare Workers Build: Requires Webpack instead of Turbopack

  • Performance impact during build (CF Workers compatibility requirement)

🔮 Future Improvements

• Real-time query streaming with WebSockets
• Advanced analytics dashboard
• Custom metric definitions
• Query performance history and trends
• Cluster topology visualization
• Advanced access control and RBAC

What's Changed

• chore(deps): update actions/cache action to v5 by @renovate[bot] in #574
• chore(deps): update nextjs monorepo to v16 (major) by @renovate[bot] in #575
• chore(deps): update nextjs monorepo to v16.1.0 by @renovate[bot] in #572
• chore(deps): update dependency next [security] by @renovate[bot] in #571
• chore(deps): update docker/login-action digest to 6862ffc by @renovate[bot] in #577
• fix(deps): update dependency next to v16 by @renovate[bot] in #581
• chore(deps): update nextjs monorepo to v16.1.1 by @renovate[bot] in #580
• fix: replace fetchDataWithHost wrapper with explicit hostId prop passing by @duyet in #582
• feat: Static Site + API with SWR refactoring complete by @duyet in #583
• fix(docker): fix static asset serving and add legacy URL redirect support by @duyet in #588
• chore(deps): update actions/checkout action to v6 by @renovate[bot] in #586
• fix(sidebar): separate text click from chevron toggle in collapsible menu items by @duyet in https://github.com/duyet/clickhou...

v0.2.0-beta.4

Full Changelog: v0.2.0-beta.3...v0.2.0-beta.4

v0.2.0-beta.3

Full Changelog: v0.2.0-beta.2...v0.2.0-beta.3

v0.2.0-beta.2

What's Changed

• fix(docker): fix static asset serving and add legacy URL redirect support by @duyet in #588
• chore(deps): update actions/checkout action to v6 by @renovate[bot] in #586
• fix(sidebar): separate text click from chevron toggle in collapsible menu items by @duyet in #589
• fix(deps): update dependency next to v16.0.9 [security] by @renovate[bot] in #590
• fix(deps): update dependency next to v16.0.10 [security] by @renovate[bot] in #591

Full Changelog: v0.2.0-beta.1...v0.2.0-beta.2

v0.2.0-beta.1

What's Changed

• chore(deps): update actions/cache action to v5 by @renovate[bot] in #574
• chore(deps): update nextjs monorepo to v16 (major) by @renovate[bot] in #575
• chore(deps): update nextjs monorepo to v16.1.0 by @renovate[bot] in #572
• chore(deps): update dependency next [security] by @renovate[bot] in #571
• chore(deps): update docker/login-action digest to 6862ffc by @renovate[bot] in #577
• fix(deps): update dependency next to v16 by @renovate[bot] in #581
• chore(deps): update nextjs monorepo to v16.1.1 by @renovate[bot] in #580
• fix: replace fetchDataWithHost wrapper with explicit hostId prop passing by @duyet in #582
• feat: Static Site + API with SWR refactoring complete by @duyet in #583

Full Changelog: v0.1.16...v0.2.0-beta.1

v0.1.16

What's Changed

• chore(deps): update dependency next to v15.4.8 [security] by @renovate[bot] in #562
• chore(deps): update dependency next [security] by @renovate[bot] in #567
• chore(deps): update actions/setup-node action to v6 by @renovate[bot] in #550
• chore: clean up by @duyet in #569

Security Update

GHSA-mwv6-3258-q52c
A vulnerability affects certain React packages for versions 19.0.0, 19.0.1, 19.1.0, 19.1.1, 19.1.2, 19.2.0, and 19.2.1 and frameworks that use the affected packages, including Next.js 15.x and 16.x using the App Router. The issue is tracked upstream as CVE-2025-55184.

A malicious HTTP request can be crafted and sent to any App Router endpoint that, when deserialized, can cause the server process to hang and consume CPU. This can result in denial of service in unpatched environments.

GHSA-w37m-7fhw-fmv9
A vulnerability affects certain React packages for versions 19.0.0, 19.0.1, 19.1.0, 19.1.1, 19.1.2, 19.2.0, and 19.2.1 and frameworks that use the affected packages, including Next.js 15.x and 16.x using the App Router. The issue is tracked upstream as CVE-2025-55183.

A malicious HTTP request can be crafted and sent to any App Router endpoint that can return the compiled source code of Server Functions. This could reveal business logic, but would not expose secrets unless they were hardcoded directly into Server Function code.

Full Changelog: v0.1.15...v0.1.16

v0.1.15

What's Changed

• fix(error-handling): make env-utils work in client components by @duyet in #544
• chore(deps): update dependency cypress to v15 by @renovate[bot] in #539
• fix(deps): update all non-major dependencies by @renovate[bot] in #545
• refactor: refactoring code, add UI tests, and clean up by @duyet in #555
• fix: fix frontend UI/UX issues by @duyet in #557
• fix: undefined hostName error in host selector by @duyet in #560
• chore(deps): update dependency node to v24 by @renovate[bot] in #554
• perf(memory): implement critical memory optimizations and nightly cleanup by @duyet in #551
• chore(deps): update actions/checkout action to v6 by @renovate[bot] in #559
• chore(deps): update docker/metadata-action digest to c299e40 by @renovate[bot] in #556
• chore(deps): update Next.js to latest version by @duyet in #563
• chore(deps): update docker/login-action digest to 28fdb31 by @renovate[bot] in #548
• refactor: code cleanup and consolidation by @duyet in #565

Full Changelog: v0.1.14...v0.1.15

v0.1.14

What's Changed

• feat: add page-views, migrate from yarn to pnpm by @duyet in #498
• fix: fix ESLint by @duyet in #499
• fix(deps): update nextjs monorepo to v15.3.4 by @renovate[bot] in #452
• Add Claude Code GitHub Workflow by @duyet in #504
• chore(test): disable test for page views configuration by @duyet in #505
• fix(deps): update all non-major dependencies by @renovate[bot] in #488
• fix(deps): update dependency react-resizable-panels to v3 by @renovate[bot] in #496
• chore(deps): update docker/login-action digest to 3d10084 by @renovate[bot] in #495
• chore(deps): update all non-major dependencies by @renovate[bot] in #507
• feat(docs): upgrade nextra@4 by @duyet in #511
• fix(deps): update dependency zod to v4 by @renovate[bot] in #508
• fix(deps): update dependency react-error-boundary to v6 by @renovate[bot] in #497
• chore(deps): update dependency eslint-plugin-cypress to v5 by @renovate[bot] in #500
• fix(deps): update dependency @hookform/resolvers to v5 by @renovate[bot] in #489
• fix(deps): update nextjs monorepo to v15.4.1 by @renovate[bot] in #506
• chore(ci): using kimi-k2 via openrouter by @duyet in #513
• fix(deps): update all non-major dependencies by @renovate[bot] in #515
• chore(deps): update all non-major dependencies by @renovate[bot] in #516
• chore(deps): update docker/metadata-action digest to be19121 by @renovate[bot] in #479
• feat: enhance error handling and table validation across the application by @duyet in #512
• feat: add Cloudflare Pages deployment support by @duyet in #530
• feat(cloudflare): deploy cloudflare workers by @duyet in #531
• fix: Add missing axis labels to chart components (#528) by @duyet in #529
• chore(deps): update actions/upload-pages-artifact action to v4 by @renovate[bot] in #525
• chore(deps): update actions/checkout action to v5 by @renovate[bot] in #524
• fix(deps): update all non-major dependencies by @renovate[bot] in #519
• chore(deps): update nextjs monorepo to v15.5.4 by @renovate[bot] in #514
• chore(deps): update dependency node to v22 by @renovate[bot] in #523
• chore(deps): update docker/login-action digest to 5e57cd1 by @renovate[bot] in #521
• chore(deps): update docker/metadata-action digest to 032a4b3 by @renovate[bot] in #522
• chore(deps): bump next from 15.4.1 to 15.4.7 in /docs by @dependabot[bot] in #526
• fix: Simplify E2E tests and complete host switching implementation by @duyet in #532
• refactor: Replace fetchDataWithHost wrapper with explicit hostId prop passing by @duyet in #534
• refactor: Replace fetchDataWithHost with fetchData (Phase 3) by @duyet in #535
• chore(deps): update dependency next to v15.4.7 [security] by @renovate[bot] in #527
• fix(menu): fix countVariant prop and text overflow in navigation menu by @duyet in #542
• chore(deps): update actions/setup-node action to v5 by @renovate[bot] in #538
• chore(deps): update all non-major dependencies by @renovate[bot] in #536
• fix(menu): filter out menu items with missing title or href by @duyet in #543
• fix(deps): update dependency @vercel/functions to v3 by @renovate[bot] in #541

Full Changelog: v0.1.13...v0.1.14

v0.1.13

What's Changed

• chore(deps): update nextjs monorepo to v15.0.4 by @renovate in #441
• fix(deps): update all non-major dependencies by @renovate in #442
• chore(ci): add support for arm64 platform in CI workflow by @duyet in #445
• fix(deps): update nextjs monorepo to v15.1.0 by @renovate in #448
• chore(deps): update docker/metadata-action digest to 906ecf0 by @renovate in #446
• fix(deps): update all non-major dependencies by @renovate in #447
• docs: update ClickHouse monitoring user privileges and explanations by @duyet in #450
• fix(deps): update all non-major dependencies by @renovate in #451
• fix(deps): update dependency react-error-boundary to v5 by @renovate in #453
• fix(deps): update all non-major dependencies by @renovate in #456
• chore(deps): update docker/metadata-action digest to 8e1d546 by @renovate in #458
• chore(deps): update docker/login-action digest to 327cd5a - autoclosed by @renovate in #457
• fix(deps): update all non-major dependencies by @renovate in #459
• fix(deps): update dependency tailwind-merge to v3 by @renovate in #465
• chore(deps): bump undici from 5.28.4 to 5.28.5 by @dependabot in #463
• fix(deps): update dependency @vercel/functions to v2 by @renovate in #469
• fix(deps): update all non-major dependencies by @renovate in #468
• chore(deps): bump katex from 0.16.19 to 0.16.21 in /docs by @dependabot in #467
• chore(deps): update dependency eslint-config-prettier to v10 by @renovate in #461
• fix(deps): update all non-major dependencies by @renovate in #470
• chore(deps): bump @octokit/plugin-paginate-rest from 9.2.1 to 9.2.2 by @dependabot in #473
• fix(deps): update dependency @hookform/resolvers to v4 by @renovate in #471
• chore(deps): bump @octokit/request-error from 5.1.0 to 5.1.1 by @dependabot in #472
• fix(deps): update all non-major dependencies by @renovate in #477
• fix(deps): update dependency react-markdown to v10 by @renovate in #478
• feat: add view refreshes configuration and menu item by @duyet in #482
• fix(deps): update all non-major dependencies by @renovate in #480
• chore(deps): update docker/login-action digest to 74a5d14 by @renovate in #483
• feat(data-table): add custom sorting functions and enhance query config by @duyet in #487
• chore: add maxDuration for /query/<id> by @duyet in #490
• feat(part-info): add part info page by @duyet in #491
• chore(deps): bump @octokit/endpoint from 9.0.5 to 9.0.6 by @dependabot in #474
• chore(deps): bump next from 15.1.0 to 15.2.4 by @dependabot in #492
• chore(deps): bump @babel/runtime from 7.26.0 to 7.27.0 by @dependabot in #486
• chore(ci): update test.yml to include CH versions 24.11, 24.12, 25.1, 25.2, and 25.3 by @duyet in #493
• chore(deps): bump dompurify from 3.2.3 to 3.2.4 in /docs by @dependabot in #475

Full Changelog: v0.1.12...v0.1.13

v0.1.12

What's Changed

• feat: add /about page by @duyet in #409
• chore(about): force static by @duyet in #410
• chore: refactor /about by @duyet in #411
• fix: database table explorer overflow by @duyet in #413
• feat: add ColumnFormat.Text column format to the data table component by @duyet in #414
• chore(deps): update codecov/codecov-action action to v5 by @renovate in #418
• fix(deps): remove package-lock.json by @duyet in #420
• chore(deps): bump cross-spawn from 7.0.3 to 7.0.5 by @dependabot in #419
• chore(deps): bump @eslint/plugin-kit from 0.2.2 to 0.2.3 in /docs by @dependabot in #415
• chore(deps): update all non-major dependencies by @renovate in #417
• chore(deps): update docker/metadata-action digest to 44d81d6 by @renovate in #416
• fix(deps): update all non-major dependencies by @renovate in #421
• feat: update /database explorer; enhance ColoredBadgeFormat with options.className; introduce ListSkeleton component by @duyet in #422
• feat: add column Markdown format by @duyet in #423
• fix(running-queries): adjust position and styling of running queries by @duyet in #426
• chore(deps): update docker/metadata-action digest to 369eb59 by @renovate in #424
• feat(docs): enhance deployment documentation by @duyet in #427
• feat: add query detail page, introduce context props for DataTable by @duyet in #428
• feat: update overview charts layout and enhance UI components by @duyet in #429
• chore(deps): update dependency @types/node to v22.9.3 by @renovate in #425
• fix(deps): update dependency tailwind-merge to v2.5.5 by @renovate in #430
• feat: enhance query detail page with cluster support and improve UI components by @duyet in #431
• feat(ci): testing configured queries against ClickHouse versions by @duyet in #433
• chore(deps): update all non-major dependencies by @renovate in #435
• chore(deps): update docker/metadata-action digest to b53be03 by @renovate in #434
• chore(deps): update dependency @cypress/code-coverage to v3.13.8 by @renovate in #436
• feat: add support for excluding monitoring users and enhance query history documentation by @duyet in #437
• chore(docs): add jitsu by @duyet in #438

Full Changelog: v0.1.11...v0.1.12