ClickHouse migration patterns and rules. Use when creating or modifying ClickHouse migrations.
Read posthog/clickhouse/migrations/AGENTS.md for comprehensive patterns, cluster setup, examples, and ingestion layer details.
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
),
]
[NodeRole.DATA]: Sharded tables (data nodes only)[NodeRole.DATA, NodeRole.COORDINATOR]: Non-sharded data tables, distributed read tables, replicated tables, views, dictionaries[NodeRole.INGESTION_SMALL]: Writable tables, Kafka tables, materialized views on ingestion layerMergeTree engines:
AggregatingMergeTree(table, replication_scheme=ReplicationScheme.SHARDED) for sharded tablesReplacingMergeTree(table, replication_scheme=ReplicationScheme.REPLICATED) for non-shardedCollapsingMergeTree, ReplacingMergeTreeDeletedDistributed engine:
Distributed(data_table="sharded_events", sharding_key="sipHash64(person_id)")Distributed(data_table="my_table", cluster=settings.CLICKHOUSE_SINGLE_SHARD_CLUSTER)ON CLUSTER clause in SQL statementsIF EXISTS / IF NOT EXISTS clausesDROP TABLE IF EXISTS ... SYNCon_cluster=Falsesharded=True when altering sharded tablesis_alter_on_replicated_table=True when altering non-sharded replicated tablesDelete entry from infi_clickhouse_orm_migrations table to re-run a migration.