| 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 against ClickHouse, or running ClickHouse in Docker Compose for local work.
Trigger with "clickhouse local dev", "clickhouse docker", "clickhouse dev
environment", "run clickhouse locally", "clickhouse docker compose".
|
| allowed-tools | Read, Write, Edit, Bash(docker:*), Bash(docker-compose:*) |
| version | 1.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","database","analytics","clickhouse","olap"] |
| compatibility | Designed for 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. This skill scaffolds a
Docker-Compose-based dev loop: an auto-migrating init script, a seed generator,
a reusable client singleton, and a truncate-between-tests integration harness —
so schema changes and query work stay a docker compose up away.
Prerequisites
- Docker or Docker Compose installed and running (
docker info succeeds).
- Node.js 18+ with the
@clickhouse/client package for the seed/test scripts.
- A local project directory you can Write files into. No cloud account or
network access is required — everything runs on
localhost.
Authentication
This is a local dev setup with no external ClickHouse Cloud service. The
container's credentials are declared inline in docker-compose.yml
(CLICKHOUSE_USER: default, CLICKHOUSE_PASSWORD: dev_password) and consumed by
the client via env vars (CLICKHOUSE_USER, CLICKHOUSE_PASSWORD,
CLICKHOUSE_HOST, CLICKHOUSE_DATABASE). Keep real per-developer overrides in a
git-ignored .env.local; commit only a .env.example. Never reuse
dev_password outside local development.
Instructions
Follow the seven-step build. The lean skeleton is below; the
full walkthrough carries the complete file
contents for every step.
-
Docker Compose setup — Write a docker-compose.yml exposing 8123
(HTTP) and 9000 (native TCP), mounting ./init-db for auto-migration and a
named volume for persistence:
services:
clickhouse:
image: clickhouse/clickhouse-server:latest
ports: ["8123:8123", "9000:9000"]
volumes:
- clickhouse-data:/var/lib/clickhouse
-
