ClickHouse v22.8.13.20-lts 更新解析三个用户可见 Bug Fix 的来龙去脉与源码印证【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本篇以 ClickHouse 官方 Changelog 归档中的 v22.8.13.20-lts.md 为主体完整覆盖该 LTS 补丁版本相对上一版 v22.8.12.45-lts 的全部变更内容3 个用户可见 Bug Fix位置参数越界异常、LowCardinality 字典远程读取失败、system.dictionaries 异常以及 6 项内部流程改进。读完后你将理解每条 changelog 记录的准确语义并能结合仓库源码定位到对应错误抛出点掌握排查上述三类问题时的验证思路。一、这份 Changelog 记录了什么ClickHouse 的每个正式版本都会在docs/changelogs/下生成一份 Markdown 归档其中 2023 年及更早的旧版本被整理到 archive 目录。本文对应的 v22.8.13.20-lts.md 标题行为ClickHouse release v22.8.13.20-lts (e4817946d18) FIXME as compared to v22.8.12.45-lts (86b0ecd5d51)这里有三处关键信息版本后缀-lts表明这是 22.8 长期支持分支的补丁版本而非主线prestable/stable开发版本22.8.13.20中第 3、4 位分别是分支号与补丁号。括号中的短哈希e4817946d18是本次发布对应的 Git commit可据此在仓库历史中精确定位该版本快照上一版基线v22.8.12.45-lts对应86b0ecd5d51。FIXME as compared to表示本版本是相对于上一个 LTS 补丁的增量变更清单——它只列出两个基线之间合入的提交而不是 22.8 分支自诞生以来的全部历史。因此阅读旧版 Changelog 时必须把它视为“相邻版本差异”而非完整特性列表。该文件内容分为两个章节Bug Fix (user-visible misbehavior in official stable release)用户可见的行为修正共 3 条是运维升级决策的主要依据NOT FOR CHANGELOG / INSIGNIFICANT不面向用户的内部流程变更发布脚本、CI/CD共 6 条。以下逐条展开。二、Bug Fix 逐条解析2.1 修复Positional argument out of bounds位置参数越界异常Changelog 原文Backported in #45565: Fix positional arguments exception Positional argument out of bounds. Closes #40634. #41189 (Kseniia Sumarokova).背景概念ClickHouse 支持位置参数positional arguments语法——在查询的表达式位置直接写一个整数字面量它会被解析为对SELECT列表中第 N 个列表达式的引用。例如SELECT 1, 2 WHERE 1 2中的1和2就是位置参数。该机制的替换逻辑在 src/Interpreters/replaceForPositionalArguments.cpp 中实现replaceForPositionalArguments函数会遍历select()-children得到列表达式列表并对候选字面量做类型与取值校验。修复点原实现对负数位置参数与越界值的边界判断存在缺陷会错误地抛出Positional argument out of bounds异常。从源码结构看该异常正是抛出点 replaceForPositionalArguments.cpp 第 61-62 行if (!pos || pos columns.size()) throw Exception(ErrorCodes::BAD_ARGUMENTS, Positional argument out of bounds: {} (expected in range [1, {}], pos, columns.size());同文件中还保留了负数索引的越界分支Negative positional argument number ... is out of bounds. Expected in range [-N, -1]见 第 47-53 行。本次 backport合入号 #45565修复 #40634PR #41189修正的就是这条校验链路中的误报路径——即合法的参数组合被错误判定为越界。对使用位置参数写法的查询尤其是通过 ORM 或程序化拼接生成的 SQL升级该版本可消除一类误报异常。2.2 二次修复Cannot read all dataLowCardinality 字典从远程文件系统读取失败Changelog 原文Backported in #44997: Another fix forCannot read all dataerror which could happen while readingLowCardinalitydictionary from remote fs. Fixes #44709. #44875 (Nikolai Kochetov).注意原文用词“Another fix”——说明此前已经有一轮针对同类错误的修复本次是补漏。这提示阅读 Changelog 时应关注“Another/Second fix”这类措辞它们往往意味着底层问题具有多个触发条件。背景LowCardinality字典是 ClickHouse 字典引擎的一种实现其列数据采用低基数压缩编码存储当字典源数据如本地/远程文件位于 S3 等远程文件系统时读取会经过本地磁盘缓存层。Cannot read all data是底层读缓冲在“期望字节数与实际读取字节数不一致”时的通用错误其典型抛出点包括通用读缓冲 src/IO/ReadBuffer.cpp 第 67 行Cannot read all data. Bytes read: {}. Bytes expected: {}.磁盘缓存读缓冲 src/Disks/IO/CachedOnDiskReadBufferFromFile.cpp 第 2013 行Cannot read all data. Offset: {} (initial offset: {}), read bytes {}/{}S3 读缓冲 src/IO/ReadBufferFromS3.cpp 第 249 行 还会附带 Key、size、expected size 与位置信息便于定位具体对象。从源码结构看CachedOnDiskReadBufferFromFile正是远程文件经本地缓存读取时的关键组件与本次“LowCardinality 字典 remote fs”的报错场景吻合反序列化 LowCardinality 字典数据时某次读取在缓存/S3 路径上提前结束导致字节数不匹配。本次 backport#44997修复 #44709PR #44875补上了剩余触发路径。排查建议若在低版本上遇到该错误可先确认字典的source配置是否指向远程对象存储、本地cache目录是否可写以及缓存文件是否损坏再评估升级到包含此修复的 LTS 补丁。2.3 修复SELECT ... FROM system.dictionaries因坏结构字典而抛异常Changelog 原文Backported in #45550: FixSELECT ... FROM system.dictionariesexception when there is a dictionary with a bad structure (e.g. incorrect type in xml config). #45399 (Aleksei Filatov).背景system.dictionaries是 ClickHouse 的字典系统表用于枚举实例中已加载的字典及其元数据。原问题在于只要实例中存在任何一个结构不合法的字典——例如字典 XML 配置里声明了错误的列类型——那么对system.dictionaries的任意查询都会整体抛异常而不是优雅地跳过或返回该字典的错误信息。这对生产环境的可观测性是严重伤害一个坏字典会“拖垮”所有基于系统表的监控查询。本次修复backport 编号 #45550PR #45399使查询system.dictionaries时不再因个别字典结构非法而中断。对于通过 XML 配置文件管理字典的部署配置示例可参考仓库文档中的字典配置章节这提升了系统表的健壮性坏字典仍应被单独修正但它不会再阻塞全局的字典巡检。三、NOT FOR CHANGELOG内部流程变更6 条这些条目不改变用户可见行为但对理解 ClickHouse 的发布机制有参考价值。全部 6 条原文如下自动合并绿色 backport PR 与绿色 approved PRPR #41110Mikhail f. ShiryaevCI 通过后的回溯合并实现自动化降低 LTS 分支人工同步成本——这正是本文这份 22.8 归档 Changelog 得以按时产出的流程基础。改进发布脚本PR #45074加固 release 构建与发布工具链。修正approved_at取值并简化条件PR #45302修复自动合并流程中时间戳判断错误。弃用 Artifactory改用 R2 ch-repos-managerPR #45421发布产物托管迁移到对象存储降低基础设施耦合。在 release workflow 中从GITHUB_TAG去掉refs/tags/前缀PR #45636修正发布工作流中标签变量的格式问题。合入普通系统表修复分支PR #38262 / #45650alesapin从功能分支回溯的普通系统表修正。从条目构成可以推断22.8 LTS 分支在该阶段的主要维护重心已从功能开发转向发布流程自动化与基础设施迁移符合 LTS 分支“只接受 backport 修复”的维护策略。四、如何阅读与核验此类 LTS Changelog结合 v22.8.13.20-lts.md 的结构阅读同类归档文件时建议遵循以下方法先看标题行的两个 commit 哈希确认增量对比基线避免把“相对上一补丁的差异”误读为“相对 GA 版本的全部变化”。区分两类章节Bug Fix (user-visible ...)是升级决策依据应逐条对照自身业务场景是否用了位置参数、字典是否走远程存储、是否依赖system.dictionariesNOT FOR CHANGELOG章节可快速扫过仅当排查发布产物或 CI 问题时再关注。善用 “Backported in #N” 编号它指向目标版本分支上的回溯合入记录可据此在版本历史中还原修复的完整链条主线 PR → backport PR → 版本发布。在源码中定位错误字符串Changelog 中用反引号标出的错误信息如Positional argument out of bounds、Cannot read all data通常就是源码中throw Exception(...)的字面量可直接在src/下全文检索定位抛出点如本文引用的 replaceForPositionalArguments.cpp#L62 与 ReadBuffer.cpp#L67从而把 changelog 描述与实际执行路径对应起来。注意同一条 Changelog 文件可能被多次归档docs/changelogs/目录中按版本存在 600 余份归档文件排查历史版本问题时可按文件名v大版本.小版本.分支.补丁-lts.md的命名规律直接检索。五、小结v22.8.13.20-lts 是一个典型的小补丁 LTS 版本3 个用户可见修复分别覆盖SQL 解析层位置参数越界误报、存储/IO 层LowCardinality 字典远程读取的二次修复、元数据层system.dictionaries 健壮性外加 6 条发布流程改进。对仍运行 22.8 分支的生产集群而言若业务涉及位置参数写法、远程存储字典或系统表监控升级到包含此补丁的版本可消除上述三类已知故障路径验证方式即为升级后重新执行此前报错的查询并核对system.dictionaries可正常查询。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考