DataHub Db2 集成测试实战：测试变体选择、Docker 环境搭建与 golden 文件校验全解析-开发者社区

数据目录
数据治理
数据血缘
后端
前端
数据工程
数据集成

【免费下载链接】datahub

The Context Platform for your Data and AI Stack

项目地址：https://gitcode.com/GitHub_Trending/da/datahub

导读

本文以 DataHub 仓库中metadata-ingestion/tests/integration/db2/NOTES_ON_TESTING_DB2.md为核心骨架，系统讲解 DataHub 的 Db2 元数据摄取（ingestion）模块在集成测试层面的完整方法论：为什么自动化测试只针对 Db2 for LUW 运行、如何通过 Docker 在 CI 中拉起真实 Db2 实例并注入测试数据、测试场景矩阵如何覆盖视图限定符、大小写敏感、注释、存储过程等边界情况，以及针对 Db2 for IBM i（AS/400）如何借助 PUB400.COM 公共服务器进行手工验证。读完本文，你将掌握 DataHub Db2 集成测试的完整链路，并理解测试背后的源码级原理。

一、Db2 家族与测试变体选择的背景

IBM Db2 并非单一数据库产品，而是一个庞大的产品家族，主流变体包括：

Db2 for LUW（Linux/Unix/Windows）：面向通用服务器，是唯一提供免费社区版（Db2 Community Edition）且能够在大多数开发者的个人电脑上运行的变体；
Db2 for IBM i（AS/400）：运行在 IBM Power Systems 上的企业级数据库，通常需要真实硬件或服务器环境，没有免费可本地运行的版本；
Db2 for z/OS：运行在大型机（mainframe）上的版本，是企业关键业务的核心，环境成本极高。

正如 NOTES_ON_TESTING_DB2.md 开头所述：

these integration tests only run against Db2 for LUW, as that is the only variant of Db2 that is freely-available and runs on most users' computers.

这一选择直接决定了整个测试矩阵的边界：自动化集成测试以 Db2 for LUW 为唯一目标，而 IBM i（AS/400）与 z/OS 依赖外部真实环境，走的是不同的验证路径。这一策略与 DataHub 的 Db2 摄取模块在 db2_pre.md 中声明支持三平台（LUW 用SYSCAT.*、z/OS 用SYSIBM.*、IBM i 用QSYS2.*）并不矛盾——支持范围与自动化测试范围是两回事，后者还受限于测试资源可用性。

二、自动化集成测试基础设施：Docker 拉起真实 Db2

Db2 集成测试的核心思路是：在 CI 环境中用 Docker 启动一个真实、可连接的 Db2 for LUW 实例，然后运行 DataHub 摄取流水线对真实数据做元数据提取。相关资源全部位于metadata-ingestion/tests/integration/db2/目录。

2.1 docker-compose.yml：容器定义与两个关键排障点

docker-compose.yml 是测试环境的核心，其要点如下：

services: testdb2: container_name: "testdb2" hostname: db2 # Pinned: 'latest' moves without notice, changing setup behavior under CI. image: icr.io/db2_community/db2:12.1.4.0 platform: linux/amd64 privileged: true entrypoint: - /bin/sh - -c - >- echo 'export DB2_4K_DEVICE_SUPPORT=ON' > /etc/profile.d/db2_4k.sh && exec /var/db2_setup/lib/setup_db2_instance.sh environment: DBNAME: testdb DB2INST1_PASSWORD: password LICENSE: accept # speed up start REPODB: false AUTOCONFIG: false ARCHIVE_LOGS: false ports: - '50000:50000' volumes: - db2data:/database volumes: db2data:

配置中有几个值得注意的工程细节：

镜像版本固定：注释明确指出'latest' moves without notice, changing setup behavior under CI，因此固定到icr.io/db2_community/db2:12.1.4.0。这是保证 CI 结果可复现的关键实践。
DB2_4K_DEVICE_SUPPORT=ON的注入方式：Db2 默认按 512 字节对齐做直接 I/O，而 CI 机器的存储往往是 4K 原生扇区，此时pwrite会以EINVAL失败，导致CREATE DATABASE以SQL0293N错误退出。由于容器启动脚本通过su - db2inst1切换用户会清空环境变量，常规的environment:注入方式无效，因此改为在 entrypoint 中先写入/etc/profile.d/db2_4k.sh再执行官方设置脚本。
数据卷必须落在真实文件系统上：注释明确指出数据库路径若位于 overlayfs 容器层上，CREATE DATABASE可能因表空间容器访问问题失败（SQL0293N），所以通过命名卷db2data:/database挂载。
加速启动的优化项：REPODB: false、AUTOCONFIG: false、ARCHIVE_LOGS: false用于缩短实例初始化时间。

2.2 测试驱动：test_db2.py 的完整流水线

test_db2.py 是集成测试的驱动主体，其执行流程可以拆解为四个阶段：

阶段一：等待数据库就绪（且能识别"假成功"）

测试通过docker_compose_runner启动容器后，调用wait_for_port(docker_services, "testdb2", DB2_PORT, timeout=600, checker=is_db2_up)等待localhost:50000端口可用。

关键在于is_db2_up函数的设计（test_db2.py）：Db2 官方容器镜像的设置脚本是"fail-open"的——即使CREATE DATABASE失败，它只打印警告（(!) Failed to create ...或 SQL 错误）并继续，最终仍输出 "Setup has completed."，服务器会启动但数据库不存在。因此测试不能靠 grep 容器日志判断就绪，而必须真实发起一次 SQLAlchemy 连接：

def _attempt_db2_connection() -> bool: engine = sqlalchemy.create_engine(DB2_URL) try: with engine.connect(): return True except Exception: return False finally: engine.dispose()

此外，连接尝试被放入一个 daemon 线程并以 30 秒硬超时兜底，原因是轮询循环的整体超时只在两次 checker 调用之间计时，若connect()内部握手卡死，既不能阻塞轮询循环，也不应阻塞解释器退出。

同时，测试会先扫描容器日志，一旦发现"(!) Failed to create"或"SQL0293N"立即抛出带诊断信息的RuntimeError（test_db2.py）。诊断信息_db2_environment_diagnostics会输出文件系统类型（df -T /database）、挂载选项、内核异步 I/O 余量（aio-nr/aio-max-nr）、设备扇区大小以及db2diag.log中 Severe/Error 级日志——这些正是定位CREATE DATABASE失败的核心证据。

阶段二：按语句切分并执行 setup.sql

Db2 的 Docker 镜像没有内置启动时执行 SQL 脚本的能力，因此 test_db2.py 用sqlglot以db2方言对setup.sql做分词切分：语句以分号分隔，但BEGIN/END块（如存储过程定义）必须保持为一个整体。实现通过统计BEGIN/CASE与END令牌的嵌套计数来决定分号是否作为语句边界。

切分后的语句通过 SQLAlchemy 引擎在事务中依次执行，连接串为：

DB2_URL = f"db2+ibm_db://db2inst1:password@localhost:{DB2_PORT}/testdb"

阶段三：运行摄取流水线并输出 MCE

每个测试用例从对应的 YAML 配置读取type: db2与schema_pattern过滤规则，然后动态注入host_port、database、username、password，构造完整的 DataHubPipeline：

config_dict = { "source": source, "sink": { "type": "file", "config": {"filename": output_path}, }, } pipeline = Pipeline.create(config_dict) pipeline.run() pipeline.raise_from_status()

输出为 MCE（Metadata Change Event）JSON 文件，落到tmp_path下。

阶段四：与 golden 文件比对

使用mce_helpers.check_golden_file将本次输出与仓库中预置的*_mces_golden.json对比，并忽略时间戳类字段：

ignore_paths=[ r"root\[\d+\]\['aspect'\]\['json'\]\['lastUpdatedTimestamp'\]", r"root\[\d+\]\['aspect'\]\['json'\].+\[\d+\]\['auditStamp'\]\['time'\]", r"root\[\d+\]\['proposedSnapshot'\].+\['aspects'\].+\['created'\]\['time'\]", ]

2.3 运行前提与平台限制

测试通过pytestmark = pytest.mark.integration_batch_4归入集成测试第 4 批次（在 setup.cfg 中声明为mark tests to run in batch 4 of integration tests），并且test_db2_ingest带有条件跳过标记：

@pytest.mark.skipif( not (platform.machine() == "x86_64" or platform.system() == "Darwin"), reason="ibm_db is not available for Linux ARM", )

这与摄取模块本身的限制一致：Db2Source.__init__在非amd64/x86_64且非 macOS 的环境会直接抛出NotImplementedError（db2.py），因为ibm_db驱动在 Linux ARM 上不可安装。但注意 db2.py 特意将ibm_db_sa的导入推迟到patch_dialect中，保证源模块在无驱动的架构上也能被导入，用户能获得友好报错而非笼统的"依赖缺失"。

三、测试场景矩阵：五组用例与 setup.sql 的精心设计

setup.sql 一次性创建了 5 个 schema，每个 schema 对应一个独立的测试场景，由 5 个 YAML 配置通过schema_pattern分别圈定。这种"一份初始化脚本 + 多份过滤配置"的结构，是测试数据复用的高效组织方式。

配置文件名	schema_pattern 过滤	测试关注点
db2_basic.yml	`basic`	基础的表、视图摄取，以及视图基于表的下游 lineage
db2_case_sensitivity.yml	`case_sensitive`	引号包裹的大小写敏感 schema/表/列名
db2_comments.yml	`comments`	表、列、视图及其列的 COMMENT 提取
db2_procedures.yml	`procedures`	存储过程的定义、注释与 lineage
db2_view_qualifier.yml	`qualifier_.*`	视图体引用其他 schema 未限定名时的限定符解析

每个用例都有对应的 golden 文件：db2_basic_mces_golden.json、db2_case_sensitivity_mces_golden.json、db2_comments_mces_golden.json、db2_procedures_mces_golden.json、db2_view_qualifier_mces_golden.json。从 db2_basic_mces_golden.json 可以看到输出 MCE 的形态——例如数据库容器实体以urn:li:container:...表示，携带containerProperties（customProperties 中包含platform: db2、env: PROD、database: TESTDB）、status、dataPlatformInstance（urn:li:dataPlatform:db2）与subTypes等 aspect，这正是 DataHub 对数据库层级容器的标准建模。

各场景对应的源码实现细节：

大小写敏感：patch_dialect（db2.py）将dialect.requires_name_normalize置为False，并覆写_reflector.normalize_name/denormalize_name为恒等函数，以规避ibm_db_sa无条件小写化导致无法区分大小写敏感表名的问题；get_db_name则把数据库名统一upper()以匹配 Db2 不区分大小写的语义。
视图限定符（view qualifier）：Db2 的视图（LUW 与 z/OS）在解析未限定名时查找的是创建视图时会话所在的 schema，而非视图自身所在 schema。get_view_default_db_schema（db2.py）通过查询SYSCAT.VIEWS.QUALIFIER（LUW）或SYSIBM.SYSVIEWS.PATHSCHEMAS（z/OS）获取隐式 schema，并对其进行引号包裹以保证大小写敏感名能无损通过 sqlglot 行级 lineage 解析。setup.sql中的qualifier_test/qualifier_target两个 schema 正是为此构造：视图qualifier_test.myview定义在 qualifier_test 中，但引用的是 qualifier_target 下未限定名的mytable。
存储过程：get_procedures_for_schema（db2.py）按平台分派——LUW 查SYSCAT.ROUTINES、z/OS 查SYSIBM.SYSROUTINES、IBM i 查QSYS2.SYSROUTINES——提取名称、语言、定义文本、注释与创建/修改时间，并同样处理QUALIFIER（过程创建时的默认 schema）。setup.sql中procedures_target.source_table → target_table的插入语句即用于验证过程的 lineage 解析。

四、针对 Db2 for IBM i（AS/400）的测试方法

自动化测试不覆盖 IBM i，是因为不存在免费可本地运行的 IBM i 环境。原文档给出的替代方案是使用公共测试服务器PUB400.COM，并明确了以下操作路径：

注册账号：在 PUB400.COM 注册新账户；
重置密码：用 5250 telnet 客户端（如tn5250）连接服务器重置密码；
配置连接参数：将"PUB400.COM"作为host_port，database传任意字符串（IBM i 下连接不依赖具体数据库名）；
执行摄取验证：复用 DataHub 的 db2 源（scheme 可按需使用db2+pyodbc400，如 db2_post.md 所述，IBM i Access ODBC Driver 需单独安装）。

为什么没有 golden 文件？原文档给出了明确原因：PUB400.COM 为每个用户创建独立的 schema，因此不同用户摄取生成的容器 URN 会不同，无法用仓库内固定的 golden 文件做比对。这是对"golden 文件对比"这类确定性测试方法的边界认知——当数据面不可控时，应退回到手工验证或结构性断言，而不是强行固化期望值。

另外注意，NOTES_ON_TESTING_DB2.md 还强调：不要对 PUB400.COM 跑自动化测试，以免过度占用这一公共资源。这体现了开源项目对免费公共设施的审慎使用原则。

五、Db2 for z/OS：状态与开放问题

对于 z/OS，源码层面（db2.py 中SYSIBM.SYSVIEWS、SYSIBM.SYSROUTINES分支以及_split_zos_pathschemas对PATHSCHEMAS的解析）已具备支持逻辑，且PATHSCHEMAS中会混入SYSFUN、SYSIBM、SYSIBMADM、SYSPROC等系统级 schema，实现会先剔除它们，若剩余多于一个 schema 则抛出NotImplementedError以显式暴露尚未支持的场景。

但测试层面缺少免费可用的 z/OS 环境。原文档最后以开放的协作姿态写道：

If you find a freely available Db2 for z/OS server to test against, please update this note.

也就是说，z/OS 的自动化测试仍是一个待社区贡献者填补的空白，任何发现免费 z/OS 测试资源的开发者都可以更新该文档，为测试矩阵补上最后一块拼图。

六、总结：Db2 集成测试方法论要点

回顾整个测试体系，可以提炼出几条可迁移到其他数据源集成测试的方法论：

测试目标与资源现实对齐：优先选择免费、可本地运行的平台变体（LUW）做自动化；对无免费环境的变体（IBM i、z/OS），要么借助公共服务器做受控的手工验证，要么显式标注为待填补空白。
容器化真实实例 + 真实连接就绪判定：不要依赖容器日志的"Setup has completed"，而应以真实数据库连接成功为就绪标准，并对"fail-open"设置脚本的失败模式做主动检测与诊断输出。
一份初始化 SQL + 多组 schema 过滤配置：用schema_pattern将不同边界场景隔离，既能复用同一份测试数据，又让每个用例的期望输出保持小而清晰。
golden 文件对比 + 忽略确定性噪声：时间戳、runId等字段在比对时显式忽略，使断言聚焦于实体结构、URN 与 metadata 内容本身。
源码级排障注释：DB2_4K_DEVICE_SUPPORT、overlayfs 卷、ibm_db_sa名称归一化等坑点都在配置与代码注释中留下了详实说明，这些注释本身就是不可多得的实战排障文档。

对于希望为 DataHub 贡献 Db2 相关改动（或为其他 SQL 数据源搭建类似集成测试）的开发者，本文涉及的仓库路径可作为起点：测试驱动 test_db2.py、环境编排 docker-compose.yml、测试数据 setup.sql、源实现 db2.py 以及平台能力说明 db2_pre.md 与 db2_post.md。