
ClickHouse v23.5.4.25-stable 补丁版本解读表函数进度条改进、缓存行为调整与一批稳定版 Bug 修复【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse导读本文基于 ClickHouse 官方仓库中的补丁发布说明文档docs/changelogs/archive/v23.5.4.25-stable.md对 v23.5 分支的第四个补丁版本 v23.5.4.25-stable 进行逐项拆解。你将了解到该补丁版本在表函数读取进度显示、文件系统缓存索引/标记文件驱逐策略、Docker 镜像构建流程三方面的改进以及查询缓存Query Cache、LDAP 认证、Parquet 格式、投影Projection执行、Azure Blob Storage、ActionsDAG 等7 项用户可见 Bug 修复的具体内容与背后的源码机制并据此评估升级决策。一、版本背景一次典型的 stable 分支补丁发布ClickHouse 的版本号遵循vYY.MM.PATCH.BUILD-stable的格式其中v23.5表示 2023 年 5 月发布的功能版本。本补丁版本v23.5.4.25-stablecommit190f962abcf是相对v23.5.3.24-stablecommit76f54616d3b的一次增量发布即 23.5 分支上的第四次补丁。值得说明的是该 changelog 的标题中保留了FIXME字样这是 ClickHouse 自动 changelog 生成流程中的已知标记不影响实际发布内容文档头部还带有sidebar_position: 1/sidebar_label: 2023的 frontmatter说明该文档在 Docusaurus 文档站中归属于 2023 年度 changelog 归档目录docs/changelogs/archive。从内容结构看本次补丁涉及四类条目分类数量说明Improvement改进2 项进度条展示、缓存驱逐设置调整Build/Testing/Packaging Improvement构建/测试/打包2 项Dockerfile 重构及其清理补丁Bug Fix用户可见 Bug 修复7 项覆盖查询缓存、LDAP、Parquet、投影执行、Azure、ActionsDAGNOT FOR CHANGELOG / INSIGNIFICANT1 项ParallelReadBuffer seek 修复其中每条Backported in说明该修复是从主分支 backport回移植到 23.5 stable 分支的这是 ClickHouse 补丁版本管理的主要流程主分支先行合并随后按补丁分支策略筛选并回移。二、Improvement两处面向用户体验的改进2.1 表函数进度条改进基于源数据 chunk 大小与线程内增量统计第一项改进针对file/s3/hdfs/url等表函数table function的进度条progress bar显示具体做法是使用源数据的 chunk 大小来计算读取进度而不是依赖固定估算在每个线程内部进行增量式的总大小total size累计同时修复了*Cluster函数如cluster、remote等分布式表函数的进度条问题对应 issue #47250PR #51088。从源码结构看ClickHouse 的进度统计核心位于 src/IO/Progress.h其中ProgressValues结构体区分了read_rows/read_bytes与total_rows_to_read/total_bytes_to_read/// See Progress. struct ProgressValues { UInt64 read_rows 0; UInt64 read_bytes 0; UInt64 total_rows_to_read 0; UInt64 total_bytes_to_read 0; ... };该结构还区分了ReadProgress、WriteProgress、ResultProgress与FileProgress其中FileProgress的注释特别说明其read_bytes是原始字节数与ReadProgress::read_bytes按列类型计算后的值不同struct FileProgress { /// Here read_bytes (raw bytes) - do not equal ReadProgress::read_bytes, which are calculated according to column types. UInt64 read_bytes 0; UInt64 total_bytes_to_read 0; ... };由此可以推断修复前进度条对file/s3/hdfs/url这类先拉取字节流、再解析列的读取场景估算不准尤其是total_bytes_to_read的填充不完整本补丁通过让每个读取线程按源数据实际 chunk 大小累计 total size使进度条能真实反映已读/总读比例。对使用者而言最直观的收益是通过s3()、url()等函数加载大文件时客户端进度条不再长时间停在 0% 或提前跳到 100%。2.2 禁用do_not_evict_index_and_mark_files缓存设置第二项改进是禁用缓存设置do_not_evict_index_and_mark_files该设置在 23.5 版本中曾默认启用对应 PR #51222。从设置名称可以推断其语义当启用时文件系统缓存filesystem cache / local cache在 LRU 驱逐eviction时会保留 MergeTree 的索引.idx与标记.mrk/.bin元数据文件避免它们被换出。但该策略在 23.5 中带来副作用例如缓存中索引/标记文件长期占位、命中率或驱逐逻辑受影响因此在补丁版本中将其改回默认关闭让索引与标记文件与其他数据一样参与正常驱逐。与这一主题相关的底层实现可以参见 src/Interpreters/FileCache/FileCacheSettings.cpp文件系统缓存的设置通过DECLARE宏集中声明其中包含驱逐策略、后台驱逐线程数、空闲空间比等参数。当前版本中还出现了将特定扩展名分类为系统缓存段system cache segments的system_cache_extensions设置DECLARE(String, system_cache_extensions, .txt,.json,.idx,.cidx,.dat, Comma-separated list of file extensions that are classified as system cache segments when use_split_cache is enabled. ..., 0)该设置的默认值包含.idx、.cidx等索引文件扩展名说明仓库后续演进对索引/标记文件在缓存中的对待方式仍在持续打磨与本补丁中禁用do_not_evict_index_and_mark_files的调整一脉相承。如果你的生产环境启用了本地文件系统缓存升级后应观察索引/标记文件在缓存中的换入换出行为并核对与驱逐相关的监控指标是否恢复预期。三、Build/Testing/PackagingDocker 镜像构建流程重构本次补丁包含两项构建流程改进PR #51504 及其清理补丁 #51564核心目标是提升 Docker 镜像构建的稳定性与安全性将 Dockerfile 中巨型RUN指令拆分为多个较小的条件化RUN不同工具按需在同一层内安装、使用后立即删除从而减小镜像层体积与缓存失效范围仅在构建开始时升级一次操作系统使用现代方式校验签名仓库signed repository将基础镜像从更高版本降级回ubuntu:20.04以解决旧版本 Docker 引擎上的兼容性问题升级 golang 版本以修复已知安全漏洞。第二项 PR 是对第一项的后续清理——重构过程中丢失了部分清理逻辑在补丁内补齐。这也体现了 ClickHouse 对构建产物可复现性的要求同一补丁分支内既要改对也要清理干净。仓库中当前的 server 镜像 Dockerfile 位于 docker/server/Dockerfile可以看到其演进后的形态开头即用独立的RUN预创建固定 uid/gid101的clickhouse用户与组再通过apt-get update --error-onany严格化仓库索引拉取随后使用ARG REPO_CHANNEL/ARG REPOSITORY/ARG VERSION参数化安装渠道与版本ARG REPO_CHANNELstable ARG REPOSITORYdeb [signed-by/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb ${REPO_CHANNEL} main ARG VERSION26.8.3.105 ARG PACKAGESclickhouse-client clickhouse-server clickhouse-common-static这种小步 RUN 参数化 ARG的结构正是本补丁所确立的构建风格。如果你是自建镜像或离线部署 ClickHouse 的团队建议使用与官方镜像相同的分层策略并为VERSION显式锁定具体补丁版本以保证可复现。四、Bug Fix 详解7 项用户可见修复4.1 查询缓存Query Cache两处独立修复修复从ColumnConst到ColumnVectorchar8_t的错误 castPR #50704查询缓存写入/读取结果列时对常量列ColumnConst的处理可能触发了错误的类型转换导致缓存命中后结果异常或崩溃。修复带子查询subquery的 SELECT 查询缓存无效的问题PR #51132此前含子查询的查询无法有效利用查询缓存本补丁打通了这条路径。查询缓存的架构核心位于 src/Interpreters/Cache/QueryResultCache.h。从该头文件的注释可以确认其设计边界缓存键Key使用查询 AST 的哈希IASTHash ast_hash而非查询字符串因此对大小写不敏感SELECT与select视为同一查询缓存不保证事务一致性当缓存内查询引用的表发生数据插入/删除时缓存不会自动失效因此必须为每个缓存条目指定 TTL过期时间过期条目会被惰性清除写入前通过checkCanWriteQueryResultCache检查查询中是否包含非确定性函数或 system 表避免缓存不确定结果。/// Maps queries to query results. Useful to avoid repeated query calculation. /// /// The cache does not aim to be transactionally consistent ... /// In order to still obtain sufficiently up-to-date query results, a expiry time (TTL) /// must be specified for each cache entry after which it becomes stale and is ignored. class QueryResultCache { public: struct Key { /// The hash of the query AST. /// Unlike the query string, the AST is agnostic to lower/upper case (SELECT vs. select). IASTHash ast_hash; ... };结合这两处修复可以推断v23.5 中查询缓存对常量列结果与子查询场景存在覆盖缺口升级到 v23.5.4.25 后这两类查询的缓存命中率与正确性均有提升。生产环境可通过系统表观察查询缓存命中情况来验证。4.2 LDAP缓存条目中服务器参数哈希类型修复PR #50865修复了 LDAP 认证服务器参数哈希server params hash在缓存条目中的类型错误。LDAP 认证在 ClickHouse 中通过config.xml的ldap_servers配置多个服务器而参数哈希用于缓存层判断LDAP 服务器配置是否发生变化、是否可复用已建立的连接/绑定。类型错误可能导致哈希比较失效使缓存错误复用或错误失效。此修复对使用 LDAP 做统一认证的部署有实际意义升级后 LDAP 连接的缓存复用将更稳定。4.3 Parquet大整数从 String 回退解析而非抛异常PR #50873Parquet 格式读取时若大整数big integer如Int128/Int256以字符串形式存储此前会直接抛出异常本补丁改为回退到从 String 解析提高了对上游数据源非标准编码的容错性。如果你经常通过file()/s3()表函数读取其他系统如 Spark、Pandas产出的 Parquet 文件此修复能减少因类型编码差异导致的加载失败。4.4 投影Projection与 read-in-order 冲突修复PR #50923当启用 read-in-order按主键顺序读取时不再应用投影projection。在 ClickHouse 中投影是表上的物化子查询存储用于加速特定聚合/排序场景而 read-in-order 优化假设按排序键顺序扫描。两者叠加时可能产生错误结果或错误计划选择因此补丁直接规定二者互斥启用 read-in-order 时跳过投影。这对依赖投影加速大宽表聚合、同时开启 read-in-order 的查询是一个重要的正确性保证。4.5 Azure Blob Storage迭代器竞态条件修复PR #50936修复了 Azure Blob Storage 迭代器iterator的竞态条件race condition。该问题影响基于azureBlobStorage表函数或 Azure 后端的s3兼容访问在多线程并发列举/读取 blob 时的稳定性可能表现为偶发的数据段重复、遗漏或崩溃。使用 Azure Blob 作为冷数据存储的部署应在升级清单中重点关注此项。4.6 ActionsDAGfuzzer 发现的崩溃修复PR #51301修复了 ActionsDAG表达式动作有向无环图即查询表达式求值计划的中间表示中的一处由 fuzzer 触发的崩溃。ClickHouse 通过持续 fuzzing 保障解析器与执行计划生成的健壮性此类修复通常只影响特定异常表达式组合下的稳定性普通查询无感但涉及任意用户输入 SQL 的对外开放实例建议尽快升级。五、NOT FOR CHANGELOG / INSIGNIFICANTParallelReadBuffer seek 修复最后一条标记为NOT FOR CHANGELOG / INSIGNIFICANT的条目修复了ParallelReadBuffer的 seek 行为PR #50820。这类条目不进入对外 changelog 汇总仅作为补丁内附带的内部修复记录在案通常影响并行读取缓冲区的定位seek逻辑属于底层 IO 稳定性的加固。六、升级建议与验证清单综合本补丁内容给出如下升级与验证建议查询缓存用户升级后可重点验证含子查询的 SELECT 与返回常量列的结果是否命中缓存并结合 TTL 设置观察命中率同时留意do_not_evict_index_and_mark_files默认值变化对本地缓存驱逐行为的影响。外部文件/对象存储加载使用file/s3/hdfs/url/azureBlobStorage表函数的场景验证大文件读取时的进度条显示以及 Parquet 大整数加载的容错性。认证与安全LDAP 部署验证认证缓存行为自建镜像的团队对照 docker/server/Dockerfile 的结构分层 RUN、参数化 VERSION、签名仓库校验审查自己的构建流程。执行正确性同时使用投影与 read-in-order 的查询升级后确认执行计划行为符合预期。版本对比基准为v23.5.4.25-stable190f962abcf→ 相对 v23.5.3.24-stable76f54616d3b。全部条目的详细说明与 PR 链接可在 docs/changelogs/archive/v23.5.4.25-stable.md 中查阅。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考