Clickhouse修改ReplicatedMergeTree列类型报Zookeeper元数据不同步错误

错误原因说明 #

你遇到的两类报错均为副本元数据同步冲突导致：

• CANNOT_ASSIGN_ALTER(517)：单副本本地元数据与ZK存储的集群公共元数据版本不匹配，无法提交ALTER任务
• UNFINISHED(341)：ALTER任务重试次数达上限，节点同步超时失败
  之前修改client_port时单节点完成、另一节点异常的操作已经破坏了集群元数据一致性，是后续报错的核心诱因。

前置检查（执行ALTER前必须完成） #

• 验证副本状态正常：执行以下SQL确认所有副本无积压、无异常

  SELECT * FROM system.replicas 
  WHERE database = 'events_db' AND table = 'events_local_tables';
  

  需满足is_active=1、is_readonly=0，queue_size/future_parts/parts_to_check无大量积压。
• 验证数据兼容性：Int16转UInt16不支持负数，提前确认无异常数据

  SELECT count(*) FROM events_db.events_local_tables 
  WHERE client_port < 0 OR server_port < 0;
  

• 检查ZK状态：确认该表对应ZK路径下无遗留的ALTER锁、无未提交的DDL日志。

正确执行流程（适用于1TB以上大表） #

大表不要直接使用ON CLUSTER执行全局ALTER，单节点故障会直接导致全局元数据不一致，推荐按以下步骤操作：

1. 逐节点执行本地ALTER：登录每个集群节点，单独执行本地修改语句，不要加ON CLUSTER参数

   ALTER TABLE events_db.events_local_tables MODIFY COLUMN client_port UInt16;
   ALTER TABLE events_db.events_local_tables MODIFY COLUMN server_port UInt16;
   

   每个节点执行完后执行DESCRIBE events_db.events_local_tables确认列类型变更成功，数据查询无异常。
2. 同步集群元数据：所有本地节点修改完成后，执行一次带ON CLUSTER的ALTER语句，此时所有节点本地元数据一致，ZK仅做同步不会触发冲突

   ALTER TABLE events_db.events_local_tables ON CLUSTER click_cluster MODIFY COLUMN client_port UInt16;
   -- 等待上一条执行完成、所有副本同步后再执行下一条
   ALTER TABLE events_db.events_local_tables ON CLUSTER click_cluster MODIFY COLUMN server_port UInt16;
   

3. 同步分布式表结构：如果有对应分布式表，执行以下语句同步结构

   ALTER TABLE events_db.events_distributed ON CLUSTER click_cluster MODIFY COLUMN client_port UInt16;
   ALTER TABLE events_db.events_distributed ON CLUSTER click_cluster MODIFY COLUMN server_port UInt16;
   

现有异常修复方案 #

你当前已出现元数据不一致问题，先按以下步骤复位再执行上述流程：

1. 备份ZK上该表对应znode的所有数据，删除/clickhouse/tables/{shard}/events_local_tables/alter_queue下的未提交ALTER任务
2. 对比两个节点的本地表结构文件/var/lib/clickhouse/metadata/events_db/events_local_tables.sql，手动调整为一致
3. 重启两个节点的ClickHouse服务，重启后检查system.replicas状态恢复正常后再执行ALTER操作

注意事项 #

• 每次执行ALTER后需等待system.mutations中对应任务完成，再提交下一个DDL
• 若确认类型转换为原地元数据操作（无数据重写），可提前调整参数延长超时时间：

  SET replicated_alter_max_retries = 10;
  SET replicated_alter_timeout = 300000;
  

内容的提问来源于stack exchange，提问作者Abid Zaidi