ClickHouse 迁移工具 - PostHog 分片与复制表管理最佳实践

clickhouse-migrations by posthog/posthog

78 周安装量

32,299 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/posthog/posthog --skill clickhouse-migrations

数据库开发运维数据处理

🇨🇳中文介绍

ClickHouse 迁移

阅读 posthog/clickhouse/migrations/AGENTS.md 以获取全面的模式、集群设置、示例和摄取层详细信息。

快速参考

迁移结构

operations = [
    run_sql_with_exceptions(
        SQL_FUNCTION(),
        node_roles=[...],
        sharded=False,  # 分片表设为 True
        is_alter_on_replicated_table=False  # 对复制表进行 ALTER 操作时设为 True
    ),
]

节点角色（根据表类型选择）

[NodeRole.DATA]: 分片表（仅数据节点）
[NodeRole.DATA, NodeRole.COORDINATOR]: 非分片数据表、分布式读取表、复制表、视图、字典
[NodeRole.INGESTION_SMALL]: 可写表、Kafka 表、摄取层上的物化视图

表引擎快速参考

MergeTree 引擎：

AggregatingMergeTree(table, replication_scheme=ReplicationScheme.SHARDED) 用于分片表

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

🇺🇸English

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 based on table type)

[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 layer

Table engines quick reference

MergeTree engines:

AggregatingMergeTree(table, replication_scheme=ReplicationScheme.SHARDED) for sharded tables
ReplacingMergeTree(table, replication_scheme=ReplicationScheme.REPLICATED) for non-sharded
Other variants: CollapsingMergeTree, ReplacingMergeTreeDeleted

Distributed engine:

Sharded: Distributed(data_table="sharded_events", sharding_key="sipHash64(person_id)")
Non-sharded: Distributed(data_table="my_table", cluster=settings.CLICKHOUSE_SINGLE_SHARD_CLUSTER)

Critical rules

NEVER use ON CLUSTER clause in SQL statements
Always use IF EXISTS / IF NOT EXISTS clauses
When dropping and recreating replicated table in same migration, use DROP TABLE IF EXISTS ... SYNC
If a function generating SQL has on_cluster param, always set on_cluster=False
Use sharded=True when altering sharded tables
Use is_alter_on_replicated_table=True when altering non-sharded replicated tables

Testing

Delete entry from infi_clickhouse_orm_migrations table to re-run a migration.

Weekly Installs

Repository

posthog/posthog

GitHub Stars

32.3K

First Seen

Feb 16, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode77

github-copilot77

codex77

kimi-cli77

amp77

gemini-cli77