Introduction

Introduction to ClickLens

ClickLens is a modern, powerful, and user-friendly web interface for managing and monitoring ClickHouse (opens in a new tab) databases. It provides a comprehensive suite of tools for developers, analysts, and administrators to interact with their ClickHouse clusters efficiently.

ClickLens Dashboard

1. Why ClickLens?

ClickHouse is an incredible analytical database, but managing it via CLI or basic tools can be challenging. ClickLens bridges the gap by offering:

  • Discover - Flexible, Kibana-like data exploration for any table
  • SQL Console - Write, execute, and analyze queries with syntax highlighting and streaming results
  • Real-time Monitoring - Keep an eye on your cluster's health, query performance, and resource usage
  • Schema Explorer - Navigate databases, tables, columns, parts, and more
  • Access Control - Manage users and roles directly from the UI
  • Native RBAC - Your UI permissions are derived directly from your ClickHouse grants
  • Multi-Cluster - Manage multiple ClickHouse clusters from a single UI

2. Key Features

FeatureDescription
DiscoverKibana-style exploration with time filtering, field selection, and histograms
SQL ConsoleMulti-tab editor with autocomplete, EXPLAIN, saved queries, and streaming
Table ExplorerBrowse schemas with parts, merges, mutations, and DDL views
Monitoring8 dashboards for metrics, cluster, disks, Keeper, and replication
Query AnalyticsRunning queries, history, performance analysis, and cache stats
LoggingServer logs, session logs, and crash logs
Access ControlUser and role management with feature roles
SettingsView server and session settings
Multi-ClusterManage multiple ClickHouse clusters from a single login screen

3. Multi-Cluster Support

ClickLens supports connecting to multiple independent ClickHouse clusters from a single instance. Each cluster is registered in the CLICKHOUSE_CLUSTERS environment variable, and users select which cluster to log into from the login page.

Quick Start (Docker Compose)

cp env.sample .env.local
# Edit .env.local with your cluster definitions
docker compose -f docker-compose.multi-cluster.yml up --build -d

Each cluster entry in CLICKHOUSE_CLUSTERS requires:

FieldDescription
idUnique identifier for the cluster
labelDisplay name shown in the UI
hostClickHouse HTTP host
portHTTP port (default 8123)
lensUserService account for metadata ops
lensPasswordService account password

Once logged in, every authenticated request is pinned to the selected cluster — queries, monitoring, schema browsing, and access control all operate against that cluster.

4. Tech Stack

ClickLens is built with modern technologies:

TechnologyVersionPurpose
Next.js16.1.1React framework with App Router
React19.2.3UI library
Tailwind CSS4.xStyling
Zustand5.0.9State management
@clickhouse/client1.15.0ClickHouse HTTP client
iron-session8.0.4Secure session management
CodeMirror6.xSQL editor
TanStack Table8.21.3Data tables
Recharts3.6.0Charts and histograms

5. Security Model

ClickLens adheres to strict RBAC principles. Your UI permissions are derived directly from your ClickHouse user's grants—the UI never adds or removes permissions.

When you log in:

  1. ClickLens authenticates against your ClickHouse server
  2. Your grants are queried to determine available features
  3. The UI shows only what you have permission to access

This means:

  • No separate permission management
  • Consistent access between CLI and UI
  • Full audit trail in ClickHouse

6. Getting Started

Ready to try ClickLens? Head to the Getting Started guide.

docker run -d \
  --name clicklens \
  -p 3000:3000 \
  -e CLICKHOUSE_CLUSTERS='[{"id":"primary","label":"Primary","host":"your-clickhouse-host","port":8123,"lensUser":"lensuser","lensPassword":"your-password"}]' \
  -e SESSION_SECRET=your-32-character-secret-key-here \
  -e NODE_ENV=production \
  ghcr.io/ntk148v/clicklens:latest

Legacy deployment: CLICKHOUSE_HOST, LENS_USER, etc. are deprecated. See the deployment guide for migration.

7. Documentation Overview

SectionAudienceContent
Getting StartedNew UsersInstallation, first login, dashboard
FeaturesEnd UsersAll features with usage instructions
ArchitectureDevelopersTech stack, data flow, internals
DeploymentOperatorsConfiguration, Docker, RBAC setup
ContributingContributorsDevelopment setup, code guidelines

AI generated documentation:

8. Screenshots

Discovery

OverviewFilterExpandable Row
discovery-overviewdiscovery-filterdiscovery-expandable-row

SQL Console

OverviewRun QueryResults
sql-overviewsql-runsql-run-result
HistoryTime RangeTable Preview
sql-historysql-time-range-selectorsql-table-preview-data

Monitoring

OverviewMetricsAsync Metrics
monitoring-overviewmonitoring-metricsmonitoring-async-metrics
DisksZooKeeper
monitoring-diskmonitoring-zookeeper

Queries

HistoryHistory FilterRunningAnalytics
queries-historyqueries-history-filterqueries-runningqueries-analytics

Access Control

UsersCreate UserEdit User
access-user-overviewaccess-user-createaccess-user-edit
RolesCreate RoleFeature Role
access-role-overviewaccess-role-createaccess-role-feature-role

Settings

Server SettingsServer ExpandableSession SettingsSession Expandable
settings-serversettings-server-expandable-rowsettings-sessionsettings-session-expandable-row

Tables

ColumnsParts
tables-columnstables-parts

Logging

Server LogsCrash Logs
logging-serverlogging-crash

Profile

User Profile
profile

9. License

MIT (opens in a new tab)

Getting Started