ClickHouse v22.12.5.34-stable 发布说明精读回移植清单与七项 Bug 修复的源码级解读【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本文以 ClickHouse 官方变更日志 v22.12.5.34-stable 为主体逐项解读该版本相对 v22.12.4.76-stable 的全部变更1 项功能改进分布式集群下 MOVE PARTITION 的副本语义与 7 项用户可见 Bug 修复SYSTEM UNFREEZE异常、QueryNormalizer别名递归、INSERT 取消导致去重失效等并结合当前仓库源码印证关键修复的落点与实现机制。读完后你将清楚该补丁版本解决了哪些生产环境真实问题以及这些修复在源码中的对应位置。版本定位与回移植机制该版本的正式标题为ClickHouse release v22.12.5.34-stable (commit b82d6401ca1)其变更基线为前一个稳定版v22.12.4.76-stable (commit cb5772db805)。从文档结构可以看出两点它属于22.12.x 长期维护分支上的补丁版本patch release而非主分支master上的功能大版本。日志文件中每一条都以 “Backported in #PR 号” 开头说明这些修复都先在 master 分支开发完成再通过backport回移植流程进入 22.12 分支最终随 stable 补丁版本发布该变更日志归档于 docs/changelogs/archive 目录页面标题为 “2023 Changelog”即它属于 2023 年发布的版本序列。这种发布模型意味着如果生产环境运行在 22.12.x 上并遇到了下列任何一类问题升级到 v22.12.5.34-stable 即可获得对应修复而不需要跨大版本迁移。本版本的完整变更清单如下Improvement 1 项 Bug Fix 7 项 杂项 4 项类别内容摘要来源 PRImprovementALTER TABLE ... ON CLUSTER ... MOVE PARTITION TO DISK/VOLUME应用到所有副本#46402Bug Fix主键重复时的键描述修复projection 场景#45686Bug FixSYSTEM UNFREEZE因CANNOT_PARSE_INPUT_ASSERTION_FAILED失败#46325Bug FixQueryNormalizer中不正确的别名递归#46609Bug FixNative TCP / HTTP 协议下 INSERT 取消不完整导致数据部分写入、去重失效#46681Bug Fixmin/max聚合优化中的算术运算错误#46705Bug FixmaxIntersections函数的 MSan 报告#46847Bug Fix分布式查询取消时可能的死锁#47161改进项MOVE PARTITION 在集群所有副本上生效问题背景ALTER TABLE table_name ON CLUSTER cluster MOVE PARTITION|PART partition_expr TO DISK|VOLUME disk_name是 ClickHouse 冷热分层存储的核心运维命令用于把指定分区迁移到其他磁盘或卷例如从 SSD 迁到 HDD或迁到对象存储。原日志给出的解释是BecauseALTER TABLE t MOVEis not replicated.即普通的ALTER TABLE t MOVE ...不通过副本机制自动同步——在 ReplicatedMergeTree 中大部分 DDL 变更通过 ZooKeeper/Keeper 的 replication queue 在各副本间复制执行但 MOVE 这类针对本地磁盘布局的操作过去不会被复制到其它副本。这就产生了一个运维陷阱管理员以为通过ON CLUSTER下发了迁移指令实际上只改动了发起查询的那个副本或仅部分副本副本间的数据落盘布局出现不一致。修复内容该版本的改进#46402使ON CLUSTER形式下带MOVE PARTITION|PART ... TO DISK|VOLUME的 ALTER 语句应用到所有副本从而保证集群内各副本的分区磁盘布局保持一致。从源码结构看分区级操作包括 MOVE PARTITION的执行路径集中在 src/Storages/PartitionCommands.cpp该文件定义了MOVE PARTITION等命令的类型与结果统计而ALTER TABLE ... ON CLUSTER的集群展开由 DDL 队列基础设施完成。这次改进正是补上了“集群展开”这一环使原本只在本节点生效的 MOVE 语义成为全集群一致的操作。对于使用冷热分层或多卷存储的生产集群这一行为变化值得在升级说明中特别注意升级后同样的运维命令会在每个副本上执行迁移引发的 IO 会在所有副本上发生。Bug Fix 1SYSTEM UNFREEZE查询解析断言失败问题描述日志原文FixSYSTEM UNFREEZEqueries failing with the exceptionCANNOT_PARSE_INPUT_ASSERTION_FAILED.SYSTEM UNFREEZE [backup_name]用于回滚SYSTEM FREEZE创建的分区备份将 frozen 数据恢复到表目录。在 v22.12.4.x 上部分SYSTEM UNFREEZE查询会因解析阶段的断言失败而直接报错错误码为CANNOT_PARSE_INPUT_ASSERTION_FAILED——这是解析器内部assertToken未满足时抛出的典型异常意味着 SQL 文本与词法/语法状态不匹配属于解析器的内部缺陷而非用户输入错误。源码印证在当前仓库中SYSTEM UNFREEZE的入口位于 src/Interpreters/InterpreterSystemQuery.cppcase Type::UNFREEZE: { getContext()-checkAccess(AccessType::SYSTEM_UNFREEZE); /// The result contains information about deleted parts as a table. It is for compatibility with ALTER TABLE UNFREEZE query. result Unfreezer(getContext()).systemUnfreeze(query.backup_name); break; }实际解冻逻辑由Unfreezer类承担见 src/Storages/Freeze.h 与 src/Storages/Freeze.cpp。从源码可以看到它的执行流程检查服务端配置项enable_system_unfreeze未开启则抛出Support for SYSTEM UNFREEZE query is disabledSUPPORT_IS_DISABLED即该命令默认是关闭的需在配置中显式开启以backup_directory_prefix/backup_name为基准遍历每个可写磁盘上的store与data两个备份目录对匹配到的表目录调用unfreezePartitionsFromTableDirectory将冻结的分区数据移回原表目录并以SYSTEM UNFREEZE为命令类型汇总结果集结果表结构与ALTER TABLE ... UNFREEZE兼容。这次修复针对的是查询从 SQL 文本走到解释器之前、解析阶段即中断的问题对应 #46325修复后依赖备份回滚机制的运维脚本在 22.12.x 上可以稳定执行。需要提醒的使用前提是SYSTEM UNFREEZE依赖SYSTEM FREEZE产生的备份目录且需要开启enable_system_unfreeze服务端设置这一点从源码中的配置校验可直接确认。Bug Fix 2QueryNormalizer中不正确的别名递归问题描述日志原文Fix incorrect alias recursion in QueryNormalizer.QueryNormalizer是 ClickHouse 中负责查询规范化query normalization的组件其典型用途包括将查询文本规范化后做缓存键、日志展示如system.query_log中脱敏后的 query 文本等。规范化过程中需要处理 SELECT 列表中的别名alias当表达式本身引用别名、或别名嵌套出现时规范化器需要递归展开。从源码结构看该组件的声明位于 src/Interpreters/QueryNormalizer.h。原实现的递归逻辑在处理别名引用链时不正确——可以推断在“别名引用别名”的嵌套场景下可能出现展开错误如展开结果与实际语义不符而极端情况下递归深度失控还可能引发栈溢出类风险。#46609 修正了这一递归的终止与展开逻辑使别名链能够被正确、有限地解析。对使用查询日志分析、查询指纹fingerprint等依赖规范化文本能力的用户该修复保证了规范化结果的准确性。Bug Fix 3INSERT 取消不完整导致数据部分写入与去重失效问题描述这是本版本中对数据可靠性影响最大的一项修复日志原文INSERTqueries through native TCP protocol and HTTP protocol were not canceled correctly in some cases. It could lead to a partially applied query if a client canceled the query, or if a client died or, in rare cases, on network errors. As a result, it could lead to not working deduplication. Fixes #27667 and #45377.拆解这条修复链触发面通过 Native TCP 协议或 HTTP 协议发起的INSERT查询在客户端主动取消、客户端进程崩溃、或较少见的网络错误等场景下服务端未能正确完成取消流程直接后果INSERT 变成“部分生效”partially applied——即数据块的接收/写入没有作为一个整体被回滚或拒绝表里留下了一次未完整提交的写入痕迹连锁后果ClickHouse 的insert_deduplication_token去重机制依赖“每次完整 INSERT 对应一个可识别的 token/块指纹”来跳过重复提交。当一次写入处于部分应用状态时去重逻辑赖以判断的前提被破坏导致去重失效not working deduplication——本应被跳过的重试写入可能被重复计入或反之去重不再按预期工作。该修复对应 #46681并关闭了历史问题 #27667 与 #45377。对依赖“失败重试 去重 token”保证 at-most-once 写入语义的 ETL 管道而言升级到此版本可消除一类隐蔽的数据重复风险。这也提示运维侧在旧版本上若出现过 INSERT 客户端中断超时、kill、断网的场景值得排查相关表是否有重复数据。Bug Fix 4min/max聚合优化中的算术运算错误日志原文Fix arithmetic operations in aggregate optimization withminandmax.ClickHouse 的聚合分析器包含一组针对min/max的代数优化例如对形如min(a)、max(a)且伴随算术表达式的查询做改写以利用已有状态或常量传播。#46705 修复了该优化路径中算术运算被错误处理的问题——可以推断为优化改写时对表达式中的算术部分如min(x) 1这类与min组合的算术子表达式推导出错导致查询结果与语义不符。这类优化器 bug 的危害在于查询跑得不报错、但结果悄悄错了属于静默正确性问题。对于大量使用 min/max 做区间、水位线类指标计算的日志与监控类查询负载该修复直接提升结果可信度升级前如对相关数字有疑问建议用关闭优化的对照查询验证。Bug Fix 5maxIntersections函数的 MSan 报告日志原文Fix MSan report in themaxIntersectionsfunction. This closes #43126.MSanMemorySanitizer用于探测读取未初始化内存的问题这类问题在普通构建中通常不可见却可能在特定平台、数据上产生不确定行为。maxIntersections是一个几何函数用于计算一组多边形Array(Array(Array(Tuple(...))))中的最大交叠面积/数量等场景其实现位于 src/AggregateFunctions/AggregateFunctionMaxIntersections.cpp。#46847 消除了 MSan 在该函数路径上的未初始化内存读取报告属于健壮性加固它保证该函数在启用内存卫生检查的构建中完全干净也降低了生产构建中潜在 UB 的风险。Bug Fix 6分布式查询取消时可能的死锁日志原文Fix possible deadlock on distributed query cancellation.在 Distributed 表/集群查询场景下当一次分布式查询被取消时参与节点之间需要在取消信号传播、子查询资源释放等环节做协调。#47161 修复了该流程中可能出现的死锁——从源码结构看分布式查询的取消涉及远端连接RemoteQueryExecutor与本地查询状态机的交互日志中未给出具体锁结构但可以推断修复方向是理顺了取消路径上的加锁/等待顺序。对生产环境的意义在于此前在“大查询被 kill”的运维动作本身可能把节点卡住线程永久阻塞、无法再响应新请求该修复提升了取消操作的可靠性和可运维性。Bug Fix 7projection 场景下重复主键时的键描述修复日志原文Fix key description when encountering duplicate primary keys. This can happen in projections. See #45590 for details.在存在projectionClickHouse MergeTree 的预聚合/二级索引式结构的表上遇到重复主键的情形时错误信息中的键描述key description不正确可能误导排障人员误判冲突键的构成。#45686 修正了该描述文本属于诊断信息正确性修复不改变查询行为但让报错信息如实反映实际的主键/排序键内容。在通过system.errors或客户端日志分析数据冲突时这一修复使排障线索不再误导。非变更日志项NOT FOR CHANGELOG / INSIGNIFICANT原日志还列出了 4 条被标注为“无需写入变更日志”的内部改动虽然对用户无直接影响但其中两条与部署/运维工具链有关值得记录systemd 集成改进Use /etc/default/clickhouse in systemd too#47003——Debian/Ubuntu 系发行版习惯把 ClickHouse 的 JVM 参数、环境变量放在/etc/default/clickhouse此前 systemd 服务单元未加载该文件此改动使clickhouse-server.service与 sysvinit 脚本行为对齐。从仓库看服务单元模板位于 packages/clickhouse-server.service该条改动直接影响在 systemd 下以发行版包方式部署的节点。发布工作流Add a manual trigger for release workflow#47302为 CI 发布流程增加了手动触发入口属于内部发布工具链增强。其余两条为 CI 侧维护跟进 #46681 的后续提交#47284以及适配新版 PyGithub 的类型标注更新#47123。升级建议与适用边界结合本版本内容给出三条实操性建议以当前仓库文档为准适用于 22.12.x 维护线运行在 v22.12.4.x 且依赖insert_deduplication_token去重的管道优先升级到 v22.12.5.34-stable消除 INSERT 取消不完整带来的去重失效风险本版本最高优先级修复使用ON CLUSTER ... MOVE PARTITION TO DISK/VOLUME做冷热分层的集群升级后该命令语义变为“所有副本生效”请在变更窗口内评估全副本迁移的 IO 影响并核对运维脚本中对该命令的预期依赖SYSTEM FREEZE/SYSTEM UNFREEZE备份回滚机制的实例确认服务端配置中已开启enable_system_unfreeze源码校验见 src/Storages/Freeze.cpp升级后重新验证回滚脚本确认不再出现CANNOT_PARSE_INPUT_ASSERTION_FAILED。需要说明的边界本文章依据的是 docs/changelogs/archive/v22.12.5.34-stable.md 这一历史版本日志其中“修复机制”的细节如分布式取消死锁的具体锁路径日志未完整披露本文对应部分已按“从源码结构看/可以推断”的口径表述当前仓库主干的代码如Unfreezer、QueryNormalizer、PartitionCommands展示了这些模块的现状实现可用于对照验证但不能逐行等同于 v22.12.5.34 发布时的快照。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考