Clickhouse Migrations

This codifies the migration patterns for ClickHouse databases, specifically the rules around sharded versus replicated tables, node roles, and table engines. You'll want this when you're working on a PostHog-style setup or any complex ClickHouse deployment where you need to coordinate migrations across clusters. The key thing it enforces is avoiding the ON CLUSTER clause and always using IF EXISTS guards, which prevents the kind of race conditions that'll wreck distributed database migrations. It's opinionated about structure, which is good because ClickHouse migration footguns are real. The cheat sheet format makes it fast to reference whether you need NodeRole.DATA or NodeRole.INGESTION_SMALL without digging through docs.

skills.sh installs: 264
GitHub stars: 40.7K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add posthog/posthog --skill clickhouse-migrations --agent claude-code

Installs into .claude/skills of the current project.

Files

ClickHouse Migrations

Read posthog/clickhouse/migrations/AGENTS.md for comprehensive patterns, cluster setup, examples, and ingestion layer details.

Quick reference

Migration structure

operations = [
    run_sql_with_exceptions(
        SQL_FUNCTION(),
        node_roles=[...],
        sharded=False,  # True for sharded tables
        is_alter_on_replicated_table=False  # True for ALTER on replicated tables
    ),
]

Node roles (choose by the cluster that owns the object)

Only the members of NodeRole in posthog/clickhouse/client/connection.py are valid: ALL, DATA, INGESTION_EVENTS, INGESTION_SMALL, INGESTION_MEDIUM, INGESTION_METRICS, ENDPOINTS, LOGS, METRICS, APM, AI_EVENTS, AUX, BATCH_EXPORTS, OPS, SESSIONS. A name that is not in that enum fails at import, which aborts migration discovery and takes every job that runs migrations down with it.