Agent skill · software engineering · jeremylongshore
clickhouse-migration-deep-dive
Execute ClickHouse schema migrations — ALTER TABLE operations, data migration between engines, versioned migration runners, and zero-downtime schema changes. Use when modifying ClickHouse schemas, migrating data between tables, or implementing versioned migration workflows. Trigger with "clickhouse migration", "clickhouse ALTER TABLE", "clickhouse schema change", "migrate clickhouse", "clickhouse add column", or "clickhouse schema migration".
Why this skill is useful
Adds specific ClickHouse migration patterns and commands that the AI wouldn't reliably generate on its own.
What it needs
Requires npm installed locally. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
ClickHouse Migration Deep Dive Overview Plan and execute ClickHouse schema migrations: column changes, engine migrations, ORDER BY modifications, and versioned migration runners. ClickHouse ALTER operations behave unlike PostgreSQL/MySQL — most are asynchronous mutations that rewrite data parts in the background, and some changes (ORDER BY, engine) require full table recreation. This skill walks the safe path for each. Prerequisites ClickHouse admin access Backup of production data (see clickhouse-prod-checklist) Test environment for validation Instructions Follow these steps in order. SQL and runner code for each step live in the linked reference files — keep them open while you work. Step 1: Classify the operation Decide whether your change is lightweight (instant, metadata only) or a heavyweight mutation (rewrites parts in the background): Step 2: Run column operations Use Edit/Write to author the ALTER TABLE statements, then apply them. Add/modify/drop columns, set materialized defaults, and attach codecs. Full DDL semantics and every column-operation variant: DDL & column operations. Step 3: Recreate the table for ORDER BY / engine changes ClickHouse has no MODIFY ORDER BY and no in-place engine change. Create a new table, INSERT ... SELECT the data, then atomically RENAME TABLE to swap. Full create → copy → swap → verify → drop recipe for both cases: table recreation. Step 4: Wire a versioned migration runner For repeatable, tracked migrations, drive numbered .sql files through a runner that records applied versions in a migrations table and stops on first failure. Use Write to scaffold runner.ts and the sql/NNN-.sql files, then run it with npm/node. Full runner, example migration files, and the operation downtime matrix: migration runner. Output Applying this skill produces: Executed ALTER statements or recreated-and-swapped tables, with mutations confirmed complete via system.mutations WHERE NOT isdone (empty result). …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clickhouse-migration-deep-dive