clickhouse-local-dev-loop

name	clickhouse-local-dev-loop
description	Run ClickHouse locally with Docker, configure test fixtures, and iterate fast. Use when setting up a local ClickHouse dev environment, writing integration tests, or running ClickHouse in Docker Compose. Trigger: "clickhouse local dev", "clickhouse docker", "clickhouse dev environment", "run clickhouse locally", "clickhouse docker compose".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(docker:*), Bash(docker-compose:*), Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","database","analytics","clickhouse","olap"]
compatible-with	claude-code

ClickHouse Local Dev Loop

Overview

Run ClickHouse in Docker for local development with fast schema iteration, seed data, and integration testing using vitest.

Prerequisites

• Docker or Docker Compose installed
• Node.js 18+ with @clickhouse/client

Instructions

Step 1: Docker Compose Setup

# docker-compose.yml
services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    ports:
      - "8123:8123"   # HTTP interface
      - "9000:9000"   # Native TCP (clickhouse-client CLI)
    volumes:
      - clickhouse-data:/var/lib/clickhouse
      - ./init-db:/docker-entrypoint-initdb.d  # Auto-run SQL on first start
    environment:
      CLICKHOUSE_USER: default
      CLICKHOUSE_PASSWORD: dev_password
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1  # Enable SQL-based user management
    ulimits:
      nofile:
        soft: 262144
        hard: 262144

volumes:
  clickhouse-data:

docker compose up -d
# Verify: curl http://localhost:8123/ping   → "Ok.\n"

Step 2: Init Script (Auto-Run on First Start)

-- init-db/001-schema.sql
CREATE DATABASE IF   app;

 IF   app.events (
    event_id    UUID  generateUUIDv4(),
    event_type  LowCardinality(String),
    user_id     UInt64,
    properties  String,     
    created_at  DateTime  now()
)
ENGINE  MergeTree()
  (event_type, created_at)
  toYYYYMM(created_at);