ClickHouse v25.8.31.9-lts 版本更新深度解读核心 Bug 修复与源码级原理分析【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本篇文章以 ClickHouse 官方 LTS 版本 v25.8.31.9-lts 的更新日志为核心逐条拆解该版本中 6 项用户可见的 Bug 修复、1 项构建/测试改进及 1 项内部优化并结合当前仓库源码如 MergeTreeSettings.cpp、MergeTreeData.cpp、MergingAggregatedMemoryEfficientTransform.cpp从实现层面解释每项修复的根因与影响面。读完本文你将理解这些修复分别解决了 JOIN 语义、文件系统缓存、数据恢复持久性、行级安全策略、分布式并行副本聚合、Parquet 读取内存安全等问题并能在升级到该版本时针对性地进行回归验证。版本概览v25.8.31.9-lts 变更总览v25.8.31.9-ltscommit95bde92a2c1是 v25.8 LTS 分支上的一个维护版本与上一版本 v25.8.30.16-ltscommit041f2f1bd67相比变更集中在三个类别类别数量涉及模块Bug Fix官方稳定版中用户可见的错误行为6 项JOIN 查询、文件系统缓存磁盘、RESTORE/备份恢复、行策略Merge 表、并行副本聚合、Parquet 输入格式Build/Testing/Packaging Improvement1 项第三方依赖 libsshNOT FOR CHANGELOG / INSIGNIFICANT1 项元数据版本文件写入所有修复均以Backported回溯移植方式合入 LTS 分支即这些修复先在上游主干验证再被移植到 LTS 维护线保证了稳定版用户可以在不升级大版本的前提下获得关键缺陷修复。JOIN 语义修复左侧为-Cluster表函数时的错误结果修复内容当查询对多个表表达式执行 JOIN且最左侧的表表达式是-Cluster表函数例如cluster(...)或remote相关的分布式表函数族时此前版本会产生错误结果。该问题在 issue [#89996] 中被报告修复 PR 为 [#94748]。背景与影响-Cluster表函数家族如clusterAllReplicas、cluster等将查询分发到集群多个节点。当它们出现在 JOIN 的最左侧时查询计划会对表函数展开为多个子查询/多路数据流在展开过程中右侧表表达式的 JOIN 键绑定关系容易在表达式重写阶段被错误处理导致匹配逻辑错乱最终返回与实际数据不符的结果集。这类错误结果在聚合或明细查询中都可能静默出现比直接报错更难排查。回归建议升级后建议使用形如SELECT ... FROM clusterAllReplicas(cluster, db.table) t1 JOIN t2 ON ...的查询做回归重点对比 JOIN 左右两表在集群/本地两种形态下的行数与聚合值是否一致。文件系统查询缓存限制下的崩溃修复enable_filesystem_query_cache_limit 1修复内容当通过开启了enable_filesystem_query_cache_limit 1的文件系统缓存磁盘filesystem cache disk读取MergeTree表时此前版本可能触发一个罕见的LOGICAL_ERROR异常 Attempt to release query context that does not exist并伴随服务器崩溃。修复 PR 为 [#107028]。根因分析该配置项为文件系统缓存引入按查询上下文限制缓存使用量的机制。查询结束后缓存层需要释放与本查询关联的上下文query context但在某些读取路径上缓存条目对应的查询上下文已被提前释放或未正确注册导致释放动作重复或找不到目标上下文抛出内部逻辑错误并终止进程。源码佐证该配置属于文件系统缓存磁盘DiskLocal之上的缓存封装相关逻辑位于 src/Disks 目录其典型配置形态是在磁盘配置中启用 filesystem cache 并设置查询缓存限制例如disk namecache_disk/name typelocal/type path/var/lib/clickhouse/cache//path cache path/var/lib/clickhouse/cache//path max_size10Gi/max_size enable_filesystem_query_cache_limit1/enable_filesystem_query_cache_limit /cache /disk回归建议在开启该配置的实例上对热点MergeTree表反复执行并发查询可用clickhouse-benchmark加压观察服务器日志是否还出现 Attempt to release query context 类异常。RESTORE 持久性修复恢复的分区文件现在会执行 fsync修复内容RESTORE从备份恢复操作现在会在目标表开启了fsync_after_insert时对恢复出来的 part 文件执行 fsync。此前恢复的文件只做了写入和关闭从未 fsync因此若在RESTORE返回RESTORED之后立即发生断电parts 文件可能处于撕裂torn状态导致表内容为空。修复 PR 为 [#111378]。根因分析fsync_after_insert是 MergeTree 引擎级别的设置其含义是对每个插入的 part 执行 fsync以保证插入数据在断电场景下与普通插入具有同等的持久性保障。但在备份恢复路径上part 文件是由备份介质直接复制/写出的恢复代码没有执行 fsync导致恢复即插入的持久性承诺出现缺口。源码佐证设置项定义在 MergeTreeSettings.cppDECLARE(Bool, fsync_after_insert, false, R( Do fsync for every inserted part. Significantly decreases performance of inserts, not recommended to use with wide parts. ), 0)该设置默认关闭false官方注释明确指出它会显著降低插入性能不建议配合 wide parts 使用。在 MergeTreeData.cpp 中恢复 part 的逻辑会读取该设置并据此决定是否 fsync/// durability an inserted part gets: fsync the file contents when the table enables fsync_after_insert. ... const bool fsync_files (*getSettings())[MergeTreeSetting::fsync_after_insert] !disk-isRemote();值得注意的是代码中 !disk-isRemote()表示远程磁盘如 S3上的 part 不会被 fsync——远程对象存储由存储侧保证持久性这一限制与文档描述一致。回归建议对开启了fsync_after_insert的表执行BACKUP/RESTORE往返测试确认恢复后数据可查、part 文件完整同时验证该配置下普通插入与恢复两条路径的持久性行为一致。行策略修复Merge 表读取后标量子查询被错误永久复用修复内容修复了一个行策略row policy缺陷——当一个包含标量子查询的行策略条件在表通过Merge表被读取后只被评估一次然后被永久复用。修复 PR 为 [#113563]。根因分析ClickHouse 的行策略条件SQL 过滤表达式会被解析并缓存供所有使用该策略的查询共享。当通过Merge表逻辑上合并多张物理表读取时读取路径会就地改写这段被缓存的表达式例如重写表名/别名绑定。由于缓存是跨查询共享的改写发生在缓存对象本身后续所有查询拿到的都是被改写后的表达式标量子查询的评估结果可能被固化导致策略条件只算一次、永远复用多个并发查询同时使用同一策略时就地改写还会引发数据竞争data race产生未定义行为。影响范围凡是依赖行策略做数据隔离如多租户场景下按user/tenant过滤且底层通过Merge表读取数据的部署都可能遇到策略过滤失效或结果不一致的问题。回归建议创建包含标量子查询如SELECT ... FROM system.settings或关联其他表的子查询的行策略挂载到Merge表执行并发查询验证过滤结果是否稳定一致。并行副本聚合修复Merge表 Distributed子表 custom-key 并行副本的异常修复内容当通过Merge表读取且其中一个子表是Distributed表同时启用了 custom-key 并行副本模式parallel_replicas_mode custom_key_sampling或custom_key_range时聚合查询可能抛出CANNOT_CONVERT_TYPE异常或在GroupingAggregatedTransform中触发异常。该问题在 issue [#113741] 中被报告修复 PR 为 [#113742]。根因分析custom-key 并行副本模式下Distributed表的数据会根据自定义键如主键或任意列表达式采样/分片到多个副本并行读取。当这样的子表被包在Merge表里时各个输入流的块chunk结构与分组键类型在两阶段聚合的合并阶段可能出现类型不一致例如不同副本返回的分组键类型推导不同进而在GroupingAggregatedTransform做桶合并时触发类型转换失败。源码佐证GroupingAggregatedTransform是两阶段聚合中负责把各节点/各输入的桶bucket按 id 对齐后输出的变换器其实现位于 MergingAggregatedMemoryEfficientTransform.cpp创建点位于 AggregatingTransform.cpp。它在输出时会检查每个 bucket 只被推送一次类型不匹配会直接反映为合并阶段的异常。回归建议构造Merge表包含Distributed子表parallel_replicas_mode custom_key_sampling的聚合查询GROUP BY主键对比启用/禁用并行副本时的结果与异常行为。Parquet 读取内存安全修复输入格式拥有读缓冲区时的堆内存损坏修复内容修复了当通过一个拥有自身读缓冲区的输入格式读取 Parquet 时的堆内存损坏问题。典型场景是使用字典dictionary数据源SOURCE(FILE(... format Parquet))。此前后台预取prefetch与解码任务可能在管道pipeline释放缓冲区之后仍继续读写该缓冲区导致堆内存损坏heap memory corruption严重时会使服务器进程中止abort。修复 PR 为 [#114668]。根因分析Parquet 读取通常采用后台预取 异步解码的流水线模式。当输入格式自身持有读缓冲区而非由外部 IO 层管理时流水线中缓冲区的生命周期归属容易在管道切换阶段出现竞态管道已经释放缓冲区但后台任务仍持有引用并继续读写形成 use-after-free。在普通文件输入下缓冲区由 IO 层管理、生命周期清晰因此问题仅在格式自持缓冲区的路径上暴露。回归建议使用Dictionary表配合SOURCE(FILE(... format Parquet))执行并发查询可用clickhouse-benchmark加压同时监控 ASan 构建或服务器日志中的堆损坏/use-after-free 报告。构建与依赖更新libssh 升级至 0.12.0修复内容将第三方库libssh从旧版本更新至0.12.0PR [#108329]。说明libssh 是 ClickHouse 用于 SSH 相关功能如基于 SSH 的文件操作的底层依赖。该升级属于构建/测试/打包类改进通常用于获取上游的 bug 修复与安全补丁。当前仓库中 libssh 的构建接入位于 contrib/libssh-cmake其源码子模块对应 contrib/libssh。回归建议升级后验证 SSH 相关功能如sftp表函数、SSH 远程文件访问的连通性与认证流程正常。内部优化元数据版本文件重写前先解除链接修复内容在重写METADATA_VERSION_FILE_NAME元数据版本文件之前先执行unlink修复了偶发的 no such key 异常。PR 为 [#87838]。说明该修复被归类为 NOT FOR CHANGELOG / INSIGNIFICANT不进入正式变更日志/影响轻微属于内部一致性优化。元数据版本文件用于记录表/库元数据的版本信息重写前先解除链接可以避免某些并发/崩溃场景下重写失败抛出键不存在异常提升元数据写入的健壮性。升级与验证建议结合上述修复清单针对 v25.8.31.9-lts 的升级验证可以按以下优先级组织数据正确性类优先回归-Cluster表函数 JOIN 结果、Merge 表下的行策略过滤、custom-key 并行副本聚合——这三类问题均属于结果错误/策略失效级别的用户可见缺陷稳定性类filesystem query cache limit 下的LOGICAL_ERROR崩溃、Parquet 堆内存损坏——两者都可能导致服务器进程中止属于生产环境高优先级关注项持久性类RESTOREfsync_after_insert组合——涉及断电场景的数据安全建议在测试环境做断电模拟验证依赖与内部类libssh 0.12.0 的 SSH 功能回归、元数据版本文件重写路径的稳定性观察。该版本涉及的底层引擎代码MergeTree 恢复路径、聚合变换器、文件系统缓存在当前仓库中均可直接查看例如 MergeTreeData.cpp 中的restorePartsFromBackup逻辑、MergeTreeSettings.cpp 中的全部 MergeTree 设置定义以及 MergingAggregatedMemoryEfficientTransform.cpp 中的两阶段聚合合并实现可作为深入理解这些修复细节的一手资料。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ClickHouse v25.8.31.9-lts 版本更新深度解读核心 Bug 修复与源码级原理分析【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本篇文章以 ClickHouse 官方 LTS 版本 v25.8.31.9-lts 的更新日志为核心逐条拆解该版本中 6 项用户可见的 Bug 修复、1 项构建/测试改进及 1 项内部优化并结合当前仓库源码如 MergeTreeSettings.cpp、MergeTreeData.cpp、MergingAggregatedMemoryEfficientTransform.cpp从实现层面解释每项修复的根因与影响面。读完本文你将理解这些修复分别解决了 JOIN 语义、文件系统缓存、数据恢复持久性、行级安全策略、分布式并行副本聚合、Parquet 读取内存安全等问题并能在升级到该版本时针对性地进行回归验证。版本概览v25.8.31.9-lts 变更总览v25.8.31.9-ltscommit95bde92a2c1是 v25.8 LTS 分支上的一个维护版本与上一版本 v25.8.30.16-ltscommit041f2f1bd67相比变更集中在三个类别类别数量涉及模块Bug Fix官方稳定版中用户可见的错误行为6 项JOIN 查询、文件系统缓存磁盘、RESTORE/备份恢复、行策略Merge 表、并行副本聚合、Parquet 输入格式Build/Testing/Packaging Improvement1 项第三方依赖 libsshNOT FOR CHANGELOG / INSIGNIFICANT1 项元数据版本文件写入所有修复均以Backported回溯移植方式合入 LTS 分支即这些修复先在上游主干验证再被移植到 LTS 维护线保证了稳定版用户可以在不升级大版本的前提下获得关键缺陷修复。JOIN 语义修复左侧为-Cluster表函数时的错误结果修复内容当查询对多个表表达式执行 JOIN且最左侧的表表达式是-Cluster表函数例如cluster(...)或remote相关的分布式表函数族时此前版本会产生错误结果。该问题在 issue [#89996] 中被报告修复 PR 为 [#94748]。背景与影响-Cluster表函数家族如clusterAllReplicas、cluster等将查询分发到集群多个节点。当它们出现在 JOIN 的最左侧时查询计划会对表函数展开为多个子查询/多路数据流在展开过程中右侧表表达式的 JOIN 键绑定关系容易在表达式重写阶段被错误处理导致匹配逻辑错乱最终返回与实际数据不符的结果集。这类错误结果在聚合或明细查询中都可能静默出现比直接报错更难排查。回归建议升级后建议使用形如SELECT ... FROM clusterAllReplicas(cluster, db.table) t1 JOIN t2 ON ...的查询做回归重点对比 JOIN 左右两表在集群/本地两种形态下的行数与聚合值是否一致。文件系统查询缓存限制下的崩溃修复enable_filesystem_query_cache_limit 1修复内容当通过开启了enable_filesystem_query_cache_limit 1的文件系统缓存磁盘filesystem cache disk读取MergeTree表时此前版本可能触发一个罕见的LOGICAL_ERROR异常 Attempt to release query context that does not exist并伴随服务器崩溃。修复 PR 为 [#107028]。根因分析该配置项为文件系统缓存引入按查询上下文限制缓存使用量的机制。查询结束后缓存层需要释放与本查询关联的上下文query context但在某些读取路径上缓存条目对应的查询上下文已被提前释放或未正确注册导致释放动作重复或找不到目标上下文抛出内部逻辑错误并终止进程。源码佐证该配置属于文件系统缓存磁盘DiskLocal之上的缓存封装相关逻辑位于 src/Disks 目录其典型配置形态是在磁盘配置中启用 filesystem cache 并设置查询缓存限制例如disk namecache_disk/name typelocal/type path/var/lib/clickhouse/cache//path cache path/var/lib/clickhouse/cache//path max_size10Gi/max_size enable_filesystem_query_cache_limit1/enable_filesystem_query_cache_limit /cache /disk回归建议在开启该配置的实例上对热点MergeTree表反复执行并发查询可用clickhouse-benchmark加压观察服务器日志是否还出现 Attempt to release query context 类异常。RESTORE 持久性修复恢复的分区文件现在会执行 fsync修复内容RESTORE从备份恢复操作现在会在目标表开启了fsync_after_insert时对恢复出来的 part 文件执行 fsync。此前恢复的文件只做了写入和关闭从未 fsync因此若在RESTORE返回RESTORED之后立即发生断电parts 文件可能处于撕裂torn状态导致表内容为空。修复 PR 为 [#111378]。根因分析fsync_after_insert是 MergeTree 引擎级别的设置其含义是对每个插入的 part 执行 fsync以保证插入数据在断电场景下与普通插入具有同等的持久性保障。但在备份恢复路径上part 文件是由备份介质直接复制/写出的恢复代码没有执行 fsync导致恢复即插入的持久性承诺出现缺口。源码佐证设置项定义在 MergeTreeSettings.cppDECLARE(Bool, fsync_after_insert, false, R( Do fsync for every inserted part. Significantly decreases performance of inserts, not recommended to use with wide parts. ), 0)该设置默认关闭false官方注释明确指出它会显著降低插入性能不建议配合 wide parts 使用。在 MergeTreeData.cpp 中恢复 part 的逻辑会读取该设置并据此决定是否 fsync/// durability an inserted part gets: fsync the file contents when the table enables fsync_after_insert. ... const bool fsync_files (*getSettings())[MergeTreeSetting::fsync_after_insert] !disk-isRemote();值得注意的是代码中 !disk-isRemote()表示远程磁盘如 S3上的 part 不会被 fsync——远程对象存储由存储侧保证持久性这一限制与文档描述一致。回归建议对开启了fsync_after_insert的表执行BACKUP/RESTORE往返测试确认恢复后数据可查、part 文件完整同时验证该配置下普通插入与恢复两条路径的持久性行为一致。行策略修复Merge 表读取后标量子查询被错误永久复用修复内容修复了一个行策略row policy缺陷——当一个包含标量子查询的行策略条件在表通过Merge表被读取后只被评估一次然后被永久复用。修复 PR 为 [#113563]。根因分析ClickHouse 的行策略条件SQL 过滤表达式会被解析并缓存供所有使用该策略的查询共享。当通过Merge表逻辑上合并多张物理表读取时读取路径会就地改写这段被缓存的表达式例如重写表名/别名绑定。由于缓存是跨查询共享的改写发生在缓存对象本身后续所有查询拿到的都是被改写后的表达式标量子查询的评估结果可能被固化导致策略条件只算一次、永远复用多个并发查询同时使用同一策略时就地改写还会引发数据竞争data race产生未定义行为。影响范围凡是依赖行策略做数据隔离如多租户场景下按user/tenant过滤且底层通过Merge表读取数据的部署都可能遇到策略过滤失效或结果不一致的问题。回归建议创建包含标量子查询如SELECT ... FROM system.settings或关联其他表的子查询的行策略挂载到Merge表执行并发查询验证过滤结果是否稳定一致。并行副本聚合修复Merge表 Distributed子表 custom-key 并行副本的异常修复内容当通过Merge表读取且其中一个子表是Distributed表同时启用了 custom-key 并行副本模式parallel_replicas_mode custom_key_sampling或custom_key_range时聚合查询可能抛出CANNOT_CONVERT_TYPE异常或在GroupingAggregatedTransform中触发异常。该问题在 issue [#113741] 中被报告修复 PR 为 [#113742]。根因分析custom-key 并行副本模式下Distributed表的数据会根据自定义键如主键或任意列表达式采样/分片到多个副本并行读取。当这样的子表被包在Merge表里时各个输入流的块chunk结构与分组键类型在两阶段聚合的合并阶段可能出现类型不一致例如不同副本返回的分组键类型推导不同进而在GroupingAggregatedTransform做桶合并时触发类型转换失败。源码佐证GroupingAggregatedTransform是两阶段聚合中负责把各节点/各输入的桶bucket按 id 对齐后输出的变换器其实现位于 MergingAggregatedMemoryEfficientTransform.cpp创建点位于 AggregatingTransform.cpp。它在输出时会检查每个 bucket 只被推送一次类型不匹配会直接反映为合并阶段的异常。回归建议构造Merge表包含Distributed子表parallel_replicas_mode custom_key_sampling的聚合查询GROUP BY主键对比启用/禁用并行副本时的结果与异常行为。Parquet 读取内存安全修复输入格式拥有读缓冲区时的堆内存损坏修复内容修复了当通过一个拥有自身读缓冲区的输入格式读取 Parquet 时的堆内存损坏问题。典型场景是使用字典dictionary数据源SOURCE(FILE(... format Parquet))。此前后台预取prefetch与解码任务可能在管道pipeline释放缓冲区之后仍继续读写该缓冲区导致堆内存损坏heap memory corruption严重时会使服务器进程中止abort。修复 PR 为 [#114668]。根因分析Parquet 读取通常采用后台预取 异步解码的流水线模式。当输入格式自身持有读缓冲区而非由外部 IO 层管理时流水线中缓冲区的生命周期归属容易在管道切换阶段出现竞态管道已经释放缓冲区但后台任务仍持有引用并继续读写形成 use-after-free。在普通文件输入下缓冲区由 IO 层管理、生命周期清晰因此问题仅在格式自持缓冲区的路径上暴露。回归建议使用Dictionary表配合SOURCE(FILE(... format Parquet))执行并发查询可用clickhouse-benchmark加压同时监控 ASan 构建或服务器日志中的堆损坏/use-after-free 报告。构建与依赖更新libssh 升级至 0.12.0修复内容将第三方库libssh从旧版本更新至0.12.0PR [#108329]。说明libssh 是 ClickHouse 用于 SSH 相关功能如基于 SSH 的文件操作的底层依赖。该升级属于构建/测试/打包类改进通常用于获取上游的 bug 修复与安全补丁。当前仓库中 libssh 的构建接入位于 contrib/libssh-cmake其源码子模块对应 contrib/libssh。回归建议升级后验证 SSH 相关功能如sftp表函数、SSH 远程文件访问的连通性与认证流程正常。内部优化元数据版本文件重写前先解除链接修复内容在重写METADATA_VERSION_FILE_NAME元数据版本文件之前先执行unlink修复了偶发的 no such key 异常。PR 为 [#87838]。说明该修复被归类为 NOT FOR CHANGELOG / INSIGNIFICANT不进入正式变更日志/影响轻微属于内部一致性优化。元数据版本文件用于记录表/库元数据的版本信息重写前先解除链接可以避免某些并发/崩溃场景下重写失败抛出键不存在异常提升元数据写入的健壮性。升级与验证建议结合上述修复清单针对 v25.8.31.9-lts 的升级验证可以按以下优先级组织数据正确性类优先回归-Cluster表函数 JOIN 结果、Merge 表下的行策略过滤、custom-key 并行副本聚合——这三类问题均属于结果错误/策略失效级别的用户可见缺陷稳定性类filesystem query cache limit 下的LOGICAL_ERROR崩溃、Parquet 堆内存损坏——两者都可能导致服务器进程中止属于生产环境高优先级关注项持久性类RESTOREfsync_after_insert组合——涉及断电场景的数据安全建议在测试环境做断电模拟验证依赖与内部类libssh 0.12.0 的 SSH 功能回归、元数据版本文件重写路径的稳定性观察。该版本涉及的底层引擎代码MergeTree 恢复路径、聚合变换器、文件系统缓存在当前仓库中均可直接查看例如 MergeTreeData.cpp 中的restorePartsFromBackup逻辑、MergeTreeSettings.cpp 中的全部 MergeTree 设置定义以及 MergingAggregatedMemoryEfficientTransform.cpp 中的两阶段聚合合并实现可作为深入理解这些修复细节的一手资料。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
