用途:规划并执行 ClickHouse 模式迁移,包括列变更、引擎迁移、ORDER BY 修改以及版本化迁移运行器。ClickHouse 的 ALTER 行为与 PostgreSQL/MySQL 不同,多数是后台重写数据分片(part)的异步 mutation,部分变更(ORDER BY、引擎)必须整表重建,本技能给出各类操作的安全路径。
主要能力:区分轻量操作(ADD COLUMN、RENAME COLUMN、COMMENT COLUMN,即时仅改元数据)与重量级 mutation(MODIFY COLUMN、DROP COLUMN、DELETE、UPDATE,后台重写分片);执行列操作并设置物化默认值与编解码器;对 ORDER BY 或引擎变更采用新建表、INSERT ... SELECT 复制、RENAME TABLE 原子交换、校验后删除旧表的流程;用编号 .sql 文件与 runner.ts 构建版本化迁移运行器,将已应用版本记录到 _migrations 表并在首次失败时停止。
使用方式:按步骤先分类操作,再执行 ALTER 或重建表,最后接入迁移运行器。监控 mutation 进度:SELECT database, table, mutation_id, is_done, parts_to_do FROM system.mutations WHERE NOT is_done ORDER BY create_time; 运行器通过 npm/node 执行。
适用场景:需要变更 ClickHouse 表结构、调整排序键或引擎、并希望迁移可重复、可追踪、尽量零停机的场景。
限制与前置条件:需要 ClickHouse 管理员权限、生产数据备份(如 BACKUP TABLE ... TO S3(...))、用于验证的测试环境;重量级 mutation 会临时占用额外磁盘空间,建议在低流量窗口执行并准备回滚方案。常见错误包括 mutation 队列已满(可 KILL MUTATION)、列已存在(用 IF NOT EXISTS)、类型不兼容(新建列回填后删旧列)、磁盘空间不足。具体 SQL 与运行器代码见资料中链接的参考文件,本资料未提供完整代码内容。