A modern, feature-rich web interface for ClickHouse databases. CH-UI provides an intuitive platform for managing ClickHouse databases, executing queries, and visualizing metrics about your instance.

• 🔄 ClickHouse Integration: Seamless connection and interaction with ClickHouse databases
• 📝 Advanced SQL Editor:
  • Intelligent IntelliSense with autocomplete suggestions
  • Syntax highlighting
  • Query history tracking
  • Multi-tab query execution
  • Query saving and management
• 📊 Dynamic Data Visualization:
  • Interactive data tables with sorting and filtering
  • Support for column names with special characters (dots, spaces, etc.)
  • Custom visualization options
  • Real-time data updates

• ⚡ Optimized Performance:
• LocalStorage-based lightweight persistence
  • Efficient state management
  • Responsive UI even with large datasets
• 🔒 TypeScript Implementation: Full TypeScript support for improved code quality and developer experience
• 📦 Custom Table Management: Built-in table handling without third-party dependencies

• 📈 Enhanced Metrics Dashboard:
  • Query performance monitoring
  • Table statistics and insights
  • System settings overview
  • Network performance metrics
  • Resource utilization tracking

• 🌐 Distributed ClickHouse Support:
  • ON CLUSTER operations for tables and users
  • Cluster-aware table creation
  • Distributed engine support
• 🔀 Reverse Proxy/Subpath Support:
  • Deploy behind nginx/apache with custom base paths
  • Flexible URL routing
  • Production-ready proxy configurations
• 🔧 Runtime Configuration:
  • Environment variables injected at Docker runtime
  • No rebuild required for configuration changes
  • Flexible deployment options

• 🎨 Modern UI/UX:
  • Clean, intuitive interface
  • Responsive design
  • Dark/Light mode support
  • Customizable layouts

docker run --name ch-ui -p 5521:5521 ghcr.io/caioricciuti/ch-ui:latest

Create a docker-compose.yml:

services:
  ch-ui:
    image: ghcr.io/caioricciuti/ch-ui:latest
    restart: always
    ports:
      - "5521:5521"
    environment:
      # Core ClickHouse Configuration
      VITE_CLICKHOUSE_URL: "http://your-clickhouse-server:8123"
      VITE_CLICKHOUSE_USER: "your-username"
      VITE_CLICKHOUSE_PASS: "your-password"
      
      # Optional: Advanced Features
      VITE_CLICKHOUSE_USE_ADVANCED: "false"
      VITE_CLICKHOUSE_CUSTOM_PATH: ""
      VITE_CLICKHOUSE_REQUEST_TIMEOUT: "30000"
      
      # Optional: Reverse Proxy Support
      VITE_BASE_PATH: "/"

Then run:

docker-compose up -d

services:
  ch-ui:
    image: ghcr.io/caioricciuti/ch-ui:latest
    restart: always
    ports:
      - "5521:5521"
    environment:
      # Core Configuration
      VITE_CLICKHOUSE_URL: "http://your-clickhouse-server:8123"
      VITE_CLICKHOUSE_USER: "your-username"
      VITE_CLICKHOUSE_PASS: "your-password"
      
      # Advanced Options
      VITE_CLICKHOUSE_USE_ADVANCED: "true"  # Enable advanced features
      VITE_CLICKHOUSE_CUSTOM_PATH: "/custom/path"  # Custom HTTP path
      VITE_CLICKHOUSE_REQUEST_TIMEOUT: "60000"  # 60 second timeout
      
      # Deployment Options
      VITE_BASE_PATH: "/ch-ui"  # Deploy at https://yourdomain.com/ch-ui

docker run --name ch-ui -p 5521:5521 \
  -e VITE_CLICKHOUSE_URL=http://your-clickhouse-server:8123 \
  -e VITE_CLICKHOUSE_USER=your-username \
  -e VITE_CLICKHOUSE_PASS=your-password \
  -e VITE_CLICKHOUSE_USE_ADVANCED=true \
  -e VITE_CLICKHOUSE_CUSTOM_PATH=/custom/path \
  -e VITE_CLICKHOUSE_REQUEST_TIMEOUT=60000 \
  -e VITE_BASE_PATH=/ch-ui \
  ghcr.io/caioricciuti/ch-ui:latest

• Node.js >= 20.x
• npm >= 10.x

# Clone the repository
git clone https://github.com/caioricciuti/ch-ui.git

# Navigate to project directory
cd ch-ui

# Install dependencies
npm install

# Build the project
npm run build

# Start for development
npm run dev

# Start for production
npm run preview

For development purposes, you can run a local ClickHouse instance using Docker:

# Start ClickHouse
docker-compose -f docker-compose-dev.yml up -d

# Stop ClickHouse
docker-compose -f docker-compose-dev.yml down

Default credentials:

• URL: http://localhost:8123
• Username: dev
• Password: dev

Data is persisted in .clickhouse_local_data directory.

When deploying CH-UI behind a reverse proxy with a custom base path:

server {
    listen 80;
    server_name your-domain.com;

    # CH-UI with custom base path
    location /ch-ui/ {
        proxy_pass http://localhost:5521/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support for real-time features
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

services:
  ch-ui:
    image: ghcr.io/caioricciuti/ch-ui:latest
    restart: always
    ports:
      - "127.0.0.1:5521:5521"  # Only bind to localhost
    environment:
      VITE_CLICKHOUSE_URL: "http://your-clickhouse-server:8123"
      VITE_CLICKHOUSE_USER: "your-username"
      VITE_CLICKHOUSE_PASS: "your-password"
      VITE_BASE_PATH: "/ch-ui"  # Must match nginx location

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location /ch-ui/ {
        proxy_pass http://localhost:5521/;
        # ... rest of proxy configuration
    }
}

server {
    listen 80;
    server_name your-domain.com;

    location /ch-ui/ {
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://localhost:5521/;
        # ... rest of proxy configuration
    }
}

CH-UI now supports distributed ClickHouse deployments with cluster operations:

• ON CLUSTER Support: Create tables and users across entire clusters
• Cluster-Aware Operations: Automatic detection of distributed setups
• Distributed Engine: Support for Distributed table engine

In your Settings page, enable "Distributed Mode" and specify your cluster name. This will:

• Enable ON CLUSTER syntax for table creation
• Enable ON CLUSTER syntax for user management
• Show cluster-specific options in the UI

1. Enable Distributed Mode in Settings
2. Create a table with "ON CLUSTER" option checked
3. Select "Distributed" as the table engine
4. CH-UI will generate the appropriate DDL with cluster syntax

If environment variables aren't being applied:

1. Ensure you're using the latest image: docker pull ghcr.io/caioricciuti/ch-ui:latest
2. Check logs: docker logs ch-ui
3. Verify variables are set: The logs should show which variables are SET/NOT SET

If CH-UI doesn't work correctly behind a reverse proxy:

1. Ensure VITE_BASE_PATH matches your proxy location
2. Don't include trailing slashes in VITE_BASE_PATH
3. Check browser console for 404 errors on assets

CH-UI now properly handles column names containing:

• Dots (e.g., user.email)
• Spaces (e.g., User Name)
• Special characters

No configuration needed - this works automatically.

For detailed documentation, visit our official documentation.

1. Reverse Proxy Support: Set VITE_BASE_PATH if deploying behind a proxy
2. Distributed ClickHouse: Enable in Settings for cluster operations
3. Enhanced Column Rendering: No changes needed, automatic improvement

None - v1.5.30 is fully backward compatible.

1. Pull the latest Docker image
2. Review new environment variables
3. Test distributed features if using ClickHouse clusters

Contributions are welcome! Please feel free to submit a Pull Request.

# Clone and install
git clone https://github.com/caioricciuti/ch-ui.git
cd ch-ui
npm install

# Run tests
npm test

# Run linter
npm run lint

# Start development server
npm run dev

Iberodata - Empowering businesses with data-driven solutions

If you find CH-UI helpful, consider supporting its development:

Your support helps maintain and improve CH-UI! ✨

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Made with ❤️ by Caio Ricciuti