用途：为 PostHog 项目创建或修改 ClickHouse 迁移时提供模式与规则参考。
主要能力与用法：
- 迁移结构使用 operations 列表，配合 run_sql_with_exceptions(SQL_FUNCTION(), node_roles=[...], sharded=False, is_alter_on_replicated_table=False)。
- 节点角色选择：分片表用 [NodeRole.DATA]；非分片数据表、分布式读表、复制表、视图、字典用 [NodeRole.DATA, NodeRole.COORDINATOR]；可写表、Kafka 表、摄入层物化视图用 [NodeRole.INGESTION_SMALL]。
- 表引擎：分片表用 AggregatingMergeTree(table, replication_scheme=ReplicationScheme.SHARDED)；非分片用 ReplacingMergeTree(table, replication_scheme=ReplicationScheme.REPLICATED)；还有 CollapsingMergeTree、ReplacingMergeTreeDeleted。分布式引擎分片与非分片写法不同。
- 关键规则：禁止使用 ON CLUSTER；始终加 IF EXISTS / IF NOT EXISTS；同迁移内删除并重建复制表需 DROP TABLE IF EXISTS ... SYNC；含 on_cluster 参数时必须设为 False；改分片表用 sharded=True；改非分片复制表用 is_alter_on_replicated_table=True。
- DROP COLUMN 为两步流程，不得自行发起；kafka_events_json_ws 与 events_json_ws_mv 禁止删除重建。
- 含迁移的 PR 必须仅含迁移文件、依赖 SQL 定义与相关测试；先合并迁移 PR 再提交应用代码。
- 本地环境需与云端一致；cloud-guarded 迁移新建表时须将 SQL 函数加入 posthog/clickhouse/schema.py 对应元组。
- 字典凭据通过 get_clickhouse_creds(ClickHouseUser.DICT_READER) 解析，不硬编码。
- 测试：删除 infi_clickhouse_orm_migrations 表中条目可重跑迁移。
限制：具体收费、平台支持、价格与效果资料暂未提供；部分内容依赖 posthog/clickhouse/migrations/AGENTS.md 详述。