用 PostgreSQL 原生回归测试套件验证 TimescaleDB：pginstallcheck 目标完整指南

用 PostgreSQL 原生回归测试套件验证 TimescaleDBpginstallcheck 目标完整指南【免费下载链接】timescaledbA time-series database for high-performance real-time analytics packaged as a Postgres extension项目地址: https://gitcode.com/gh_mirrors/ti/timescaledbTimescaleDB 作为 PostgreSQL 扩展深度修改了规划器planner与 DDL 钩子hooks因此其改动是否与标准 PostgreSQL 行为兼容至关重要。本文介绍仓库中 test/pgtest 目录提供的pginstallcheckCMake 目标如何在加载 TimescaleDB 扩展的情况下直接运行 PostgreSQL 自带的src/test/regress回归测试套件以及这一机制的底层实现原理。读完本文你将掌握从配置PG_SOURCE_DIR、生成构建目录到执行make pginstallcheck的完整流程并理解测试计划schedule如何被裁剪、扩展如何被预加载。为什么需要运行 PostgreSQL 原生测试套件TimescaleDB 不是传统的纯 SQL 层扩展——它在 C 层面介入 PostgreSQL 的核心执行路径在规划阶段src/planner/planner.c 中的钩子会拦截查询计划将针对 hypertable 的查询改写为面向多个 chunk 的查询在 DDL 阶段src/process_utility.c 会拦截CREATE TABLE、ALTER TABLE等语句自动把普通表转换为 hypertable 并维护维度、chunk 等元数据。这种深层次的侵入意味着任何对 PostgreSQL 内部接口的误用都可能让扩展与原生 PostgreSQL 行为产生冲突而这类冲突往往只有在大规模标准测试中才会暴露。test/pgtest/README.md 明确指出运行标准 PostgreSQL 测试套件的价值就在于确保 TimescaleDB 修改的 planner 和 DDL 钩子与标准 PostgreSQL 兼容。因此test/pgtest目录的目标不是测试 TimescaleDB 自己的功能那由 test/sql 和 tsl/test 下的回归测试负责而是用 PostgreSQL 官方的测试资产做兼容性体检。前置条件运行pginstallcheck需要满足以下条件PostgreSQL 源码树必须能访问 PostgreSQL 的源码测试资产SQL 脚本、期望输出、数据文件将从src/test/regress目录复制出来源码树已编译至少src/test/regress目录需要完成编译因为pg_regress工具和测试所需的二进制组件依赖构建产物TimescaleDB 构建环境就绪通常指已通过bootstrap脚本初始化好 CMake 构建目录并已安装/可加载 TimescaleDB 扩展。仓库当前支持的 PostgreSQL 主版本为 15、16、17 和 18见 CMakeLists.txt 中的版本检查使用与目标版本匹配的 PostgreSQL 源码树即可。配置构建定位 PostgreSQL 源码树pginstallcheck目标依赖PG_SOURCE_DIRCMake 变量来定位 PostgreSQL 源码树。顶层 CMakeLists.txt 会尝试自动探测该路径find_path( PG_SOURCE_DIR src/include/pg_config.h.in HINTS $ENV{HOME} $ENV{HOME}/projects $ENV{HOME}/Projects $ENV{HOME}/development $ENV{HOME}/Development $ENV{HOME}/workspace PATH_SUFFIXES postgres postgresql pgsql DOC The path to the PostgreSQL source tree)也就是说如果 PostgreSQL 源码位于$HOME/postgres、$HOME/projects/postgresql之类的常见目录下CMake 会在配置阶段自动找到它并在输出中打印Found PostgreSQL source in /path/to/postgresql如果自动探测失败则需要手动指定这是 README 中给出的标准配置方式。在 TimescaleDB 源码树的顶层目录执行$ mkdir build cd build $ cmake -DPG_SOURCE_DIRpath/to/pg/source ..其中path/to/pg/source应替换为 PostgreSQL 源码树的绝对路径即包含src/include/pg_config.h.in的目录。注意find_path探测的 HINTS 路径会作为默认值缓存而显式传入的-DPG_SOURCE_DIR优先级最高。只有配置阶段成功解析出PG_SOURCE_DIR后test/CMakeLists.txt 才会把pgtest子目录纳入构建if(PG_SOURCE_DIR) add_subdirectory(pgtest) endif(PG_SOURCE_DIR)换句话说没有 PostgreSQL 源码树时pginstallcheck目标根本不会生成。运行测试make pginstallcheckCMake 配置完成后直接执行$ make pginstallcheck该命令的核心行为由 test/pgtest/CMakeLists.txt 定义add_custom_target( pginstallcheck COMMAND ${PG_REGRESS} ${PG_REGRESS_OPTS_BASE} ${PG_REGRESS_OPTS_PGTEST} ${PG_REGRESS_OPTS_TEMP_INSTANCE_PGTEST} USES_TERMINAL)其中${PG_REGRESS}是pg_regress回归测试驱动程序位于 PostgreSQL 安装目录的bin下${PG_REGRESS_OPTS_PGTEST}指定了裁剪后的测试计划并加载 TimescaleDB 扩展set(PG_REGRESS_OPTS_PGTEST --schedule${CMAKE_CURRENT_BINARY_DIR}/schedule --load-extensiontimescaledb)${PG_REGRESS_OPTS_TEMP_INSTANCE_PGTEST}让pg_regress启动一个临时 PostgreSQL 实例与 TimescaleDB 自身的回归测试共用同一套临时实例机制并注入专为该测试准备的配置set(PG_REGRESS_OPTS_TEMP_INSTANCE_PGTEST --temp-instance${TEST_CLUSTER}-pg --temp-config${TEST_OUTPUT_DIR}/pgtest.conf)pgtest.conf由模板 test/pgtest.conf.in 生成内容非常精简但关键# postgresql.conf settings for PostgreSQL test suite shared_preload_librariestimescaledb TELEMETRY_DEFAULT_SETTINGshared_preload_librariestimescaledb确保扩展在实例启动时就随共享库预加载这也是 TimescaleDB 注册钩子、共享内存结构所必需的前提TELEMETRY_DEFAULT_SETTING则根据构建时是否开启遥测USE_TELEMETRY见 test/test-defs.cmake展开为timescaledb.telemetry_leveloff或留空保证测试环境默认关闭遥测、行为可复现。底层机制剖析测试资产如何搬运与裁剪pginstallcheck的魔法在 CMake 配置阶段就已经完成。运行make pginstallcheck之前CMake 会依次做四件事全部位于 test/pgtest/CMakeLists.txt1. 复制测试资产set(PG_REGRESS_DIR ${PG_SOURCE_DIR}/src/test/regress CACHE PATH Path to PostgreSQLs regress directory) set(PGTEST_DIRS ${PG_REGRESS_DIR}/data ${PG_REGRESS_DIR}/sql ${PG_REGRESS_DIR}/expected) file(COPY ${PGTEST_DIRS} DESTINATION ${CMAKE_CURRENT_BINARY_DIR})data回归测试用的数据文件、sql测试 SQL 脚本和expected期望输出三个目录被整体复制到 TimescaleDB 的构建输出目录。注释解释了原因测试套件会从模板源文件生成一些 SQL 脚本和输出文件要求这些目录与输出目录同处一地colocated。2. 读取并裁剪测试计划file(READ ${PG_REGRESS_DIR}/parallel_schedule PG_TEST_SCHEDULE)PostgreSQL 的回归测试由src/test/regress/parallel_schedule文件编排pg_regress按该计划顺序执行各组测试。TimescaleDB 从中读取完整计划后按需剔除与扩展环境冲突的用例。3. 准备 tablespace 测试目录file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/testtablespace)回归测试套件中的tablespace测试需要真实的目录来创建表空间因此预先在构建目录下建好。4. 从计划中剔除不兼容测试set(PG_IGNORE_TESTS advisory_lock amutils database event_trigger jsonb_jsonpath opr_sanity sanity_check type_sanity create_am select_parallel psql)这 11 项测试被从parallel_schedule中移除原因可归为几类依赖特定扩展/模块amutils需要amcheck等、jsonb_jsonpath测试脚本依赖database、event_trigger等涉及全局状态与扩展共存时行为不稳定与扩展冲突的 sanity 检查opr_sanity、sanity_check、type_sanity会严格校验系统目录pg_catalog等内容的一致性而 TimescaleDB 预加载后会改变部分目录状态这类白盒校验不再适用行为与版本/并发相关select_parallel在不同版本下会派生不同数量的并行 worker注释明确说明因此被忽略psql、advisory_lock等涉及客户端交互或全局锁语义。值得注意的实现细节同样写在 CMake 注释中pg_regress 在 PG16 移除了--ignore选项对应 PostgreSQL 提交 bd8d453e9b5f8b632a400a9e796fc041aed76d82因此这里不再依赖运行时的忽略参数而是通过string(REPLACE ...)把对应测试行从 schedule 文本中直接删除再写回裁剪后的计划文件foreach(IGNORE_TEST ${PG_IGNORE_TESTS}) string(REPLACE test: ${IGNORE_TEST}\n PG_TEST_SCHEDULE ${PG_TEST_SCHEDULE}) string(REPLACE ${IGNORE_TEST} PG_TEST_SCHEDULE ${PG_TEST_SCHEDULE}) string(REPLACE ${IGNORE_TEST}\n \n PG_TEST_SCHEDULE ${PG_TEST_SCHEDULE}) endforeach(IGNORE_TEST) file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/schedule ${PG_TEST_SCHEDULE})最终生成的schedule文件就是--schedule参数指向的输入意味着测试内容会随 PostgreSQL 源码版本自动同步而排除清单则由 TimescaleDB 维护。配套目标pginstallchecklocal除了临时实例模式test/pgtest/CMakeLists.txt 还定义了pginstallchecklocaladd_custom_target( pginstallchecklocal COMMAND ${PG_REGRESS} ${PG_REGRESS_OPTS_BASE} ${PG_REGRESS_OPTS_PGTEST} ${PG_REGRESS_OPTS_LOCAL_INSTANCE} USES_TERMINAL)两者共享同一份裁剪后的 schedule 和--load-extensiontimescaledb唯一区别是连接方式pginstallcheck使用--temp-instance启动一次性临时集群用完即销毁适合 CI 和本地快速验证而pginstallchecklocal通过${PG_REGRESS_OPTS_LOCAL_INSTANCE}连接到一个已经运行中的 PostgreSQL 实例set(PG_REGRESS_OPTS_LOCAL_INSTANCE --host${TEST_PGHOST} --port${TEST_PGPORT_LOCAL})TEST_PGHOST默认localhost、TEST_PGPORT_LOCAL默认5432见 test/test-defs.cmake均可通过 CMake 缓存变量覆盖。这种模式适合需要在特定配置、特定数据的常驻实例上反复调试的场景。与 TimescaleDB 自身测试体系的关系在仓库的整体测试架构中pginstallcheck是一个独立补充层TimescaleDB 自身的 SQL 回归测试由regresscheck临时实例与regresschecklocal本地实例驱动测试资产位于 test/sql 与 tsl/test/sql统一由 test/CMakeLists.txt 中的pg_regress.sh包装器执行pginstallcheck则完全复用 PostgreSQL 官方src/test/regress的资产目标指向兼容性而非功能正确性只有当PG_SOURCE_DIR被解析到且REGRESS_CHECKS开启从而找到pg_regress时该目标才会出现在构建系统中。两者互补前者验证 TimescaleDB 自身的 hypertable、压缩、连续聚合等功能后者验证扩展加载后不会破坏 PostgreSQL 的任何原生行为。对于计划在 CI 中同时跑两者的团队建议在配置阶段显式传入-DPG_SOURCE_DIR避免自动探测在无头环境中失败若要在已有实例上快速复核make pginstallchecklocal无需反复启停临时集群是更轻量的选择。小结pginstallcheck是 TimescaleDB 为保证扩展与 PostgreSQL 内核深度耦合仍不破坏原生行为而设计的兼容性测试通道。其核心链路可以概括为PG_SOURCE_DIR定位源码 → CMake 复制src/test/regress资产并读取parallel_schedule→ 剔除 11 项冲突测试生成新 schedule →pg_regress以--load-extensiontimescaledb在临时实例或本地实例上执行全套原生回归测试。无论是扩展开发者验证钩子改动还是发布前的兼容性回归这一目标都值得纳入常规测试流程。更多细节可继续阅读 test/pgtest/CMakeLists.txt 与 test/pgtest/README.md 原文。【免费下载链接】timescaledbA time-series database for high-performance real-time analytics packaged as a Postgres extension项目地址: https://gitcode.com/gh_mirrors/ti/timescaledb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考