数据工程数据集成ETL后端大数据【免费下载链接】airbyteOpen-source data movement for ELT pipelines and AI agents — from APIs, databases files to warehouses, lakes, and AI applications. Both self-hosted and Cloud.项目地址https://gitcode.com/gh_mirrors/ai/airbyte点击查看免费下载本文围绕 Airbyte 仓库中source-postgres连接器的本地端到端测试技能SKILL.md展开讲解如何用 Docker 拉起 PostgreSQL 16 后端、注入 SQL fixtures并通过airbyte-ops cloud connector regression-test对任意airbyte/source-postgres:tag镜像执行完整的 Airbyte 协议命令扫描。读完本文你将掌握一套可复现 bug、可对比新旧镜像、可声明式断言输出的本地测试工作流并理解其底层脚本与共享库的实现原理。一、技能定位本地端到端测试挂架source-postgres-e2e-tests是source-postgres连接器目录下的一个 Agent 技能skill它的作用是在开发者本机快速拉起一套最小可用的 PostgreSQL 测试环境然后对任意版本的source-postgres连接器镜像跑一遍 Airbyte 协议命令启动名为source-postgres-db-backend的 PostgreSQL 16 容器向其中应用任意 SQL fixtures建表、造数针对任意airbyte/source-postgres:tag镜像通过airbyte-ops cloud connector regression-test依次执行spec→check→discover→read。引擎无关engine-independent的编排逻辑并不放在连接器目录内而是沉淀在仓库级的共享库airbyte-integrations/db-harness-lib/中本技能只保留 PostgreSQL 后端的生命周期脚本、fixtures 与配置模板。由于共享库位于连接器目录之外对它所做的改动不会触发连接器版本号的变更。需要明确的能力边界是该技能目前只支持标准非 CDC模式的本地扫描。CDC fixtures 与复制replication搭建不在本技能范围内但后端的启动脚本已经以wal_levellogical开启了逻辑复制以便配套的 source-postgres-e2e-cdc-tests 技能 复用同一个后端。二、适用场景何时使用本技能按 SKILL.md 的说明本技能主要面向三类开发任务本地复现source-postgres的 bug拿到一个异常行为描述后用可控的后端数据与固定版本的镜像把问题稳定复现出来连接器开发期间做协议扫描对任意airbyte/source-postgres:tag单独跑spec、check、discover、read中的某一个或按顺序全量跑证明修复有效用--control-version把目标镜像修复后与对照镜像修复前在同一后端上做 A/B 对比验证行为差异。三、环境准备使用本技能需要以下前置条件SKILL.mdDocker用于运行 PostgreSQL 后端容器与连接器容器uv用于安装airbyte-ops。执行uv tool install airbyte-internal-ops后airbyte-ops会被放到$PATH上如果不想全局安装也可以用uvx airbyte-internal-ops前缀调用run-protocol-cmd.sh 会先探测$PATH上的airbyte-ops找不到时自动回退到uvx airbyte-internal-opsjq用于配置渲染与 catalog 派生等 JSON 处理一份 Airbyte 仓库克隆技能脚本依赖仓库内的db-harness-lib共享库与连接器源码。不需要 GSM密钥管理或 Cloud 管理员凭据。本地模式不带--connection-id下所有输入都从本地文件读取。四、目录布局与职责划分技能目录结构如下SKILL.mdsource-postgres-e2e-tests/ ├── SKILL.md ├── scripts/ │ ├── start-backend.sh # docker run postgres:16 with logical replication │ ├── apply-sql.sh # docker exec psql on stdin │ ├── reset-databases.sh # drop and recreate non-system databases │ └── run.sh # engine shim to db-harness-lib orchestration └── fixtures/ ├── configs/ │ └── base.template.json # STANDARD config; host placeholder └── sql/ └── 00-init-base.sql # sample table with three rows职责划分引擎 shimrun.sh与生命周期脚本留在技能的scripts/目录共享编排与协议辅助逻辑在airbyte-integrations/db-harness-lib/。共享库的脚本包括run.sh协议扫描主入口负责 spec/check/discover/read 的完整编排、退出码与产物布局run-protocol-cmd.sh针对单条协议命令调用airbyte-opsmake-catalog.sh从 discover 输出机械地派生 configured catalogrender-config.sh用后端容器的 bridge IP 替换配置模板中的 hoststop-backend.sh默认的后端清理脚本幂等extract-state.py从 JSONL 输出中提取 Airbyte STATE 消息。技能脚本期望所有脚本路径都相对于技能根目录解析。五、核心约定与可覆盖的环境变量5.1 命名与默认值约定项默认值说明容器名source-postgres-db-backend硬编码在生命周期脚本中可用BACKEND_NAME…覆盖仅用于并行测试隔离不要使用客户连接名Postgres 密码test_password运行隔离本地后端时可用BACKEND_PASSWORD覆盖初始数据库test_db使用不同 fixture 数据库时可用BACKEND_DB覆盖后端镜像postgres:16固定大版本以保持行为稳定而非跟随latest可用BACKEND_IMAGE…覆盖以复现特定版本问题工作目录${REPRO_OUT:-/tmp/source-postgres-repro}渲染后的配置与运行产物所在位置这些默认值都能在源码中找到容器启动参数见 start-backend.shshim 中对BACKEND_NAME的默认赋值见 run.sh技能。5.2 后端启动细节start-backend.sh 是幂等的若同名容器已在运行则直接复用否则删除旧容器并重新拉起并携带以下关键参数docker run -d --rm \ --name $BACKEND_NAME \ -e POSTGRES_PASSWORD$BACKEND_PASSWORD \ -e POSTGRES_DB$BACKEND_DB \ -p $BACKEND_PORT:5432 \ $BACKEND_IMAGE \ -c wal_levellogical \ -c max_replication_slots10 \ -c max_wal_senders10wal_levellogical与 replication slot/sender 上限的配置正是为了让 CDC 技能可以复用同一个后端即便本技能自身不跑 CDC。启动后脚本会在最多 120 秒内轮询psql -c SELECT 1等待后端就绪。5.3 网络与配置渲染两个容器PostgreSQL 后端与airbyte-ops启动的连接器容器共享 Docker 默认的bridge网络。由于本地regression-test命令目前不接受--network参数连接器无法通过容器名解析后端因此共享的 render-config.sh 会在运行时通过docker inspect取出后端的 bridge IP并把它替换进工作配置的.host字段BACKEND_IP$(docker inspect $BACKEND_NAME \ --format {{.NetworkSettings.Networks.bridge.IPAddress}}) jq --arg h $BACKEND_IP $CONFIG_HOST_JQ $TEMPLATE $OUTPUT默认的 jq 表达式是CONFIG_HOST_JQ${CONFIG_HOST_JQ:-.host \$h}如果某个引擎的配置把 host 放在不同位置可以覆盖CONFIG_HOST_JQ。此行为在 airbytehq/airbyte-ops-mcp#765 落地--network支持之前会一直存在此链接仅作追踪引用不属于本仓库。5.4 配置模板与 SQL fixture标准非 CDC配置模板 base.template.json 内容如下{ host: source-postgres-db-backend, port: 5432, database: test_db, schemas: [public], username: postgres, password: test_password, ssl_mode: { mode: prefer }, tunnel_method: { tunnel_method: NO_TUNNEL }, replication_method: { method: Standard } }值得注意的两个 Postgres 专属配置形状ssl_mode.mode使用prefer本地明文后端标准同步的replication_method.method必须是StandardCDC 场景才改为CDC。默认 fixture 00-init-base.sql 是幂等的基础初始化脚本test_db数据库由容器通过POSTGRES_DB创建fixture 只负责重新创建一张三行数据的示例表DROP TABLE IF EXISTS sample; CREATE TABLE sample ( id INT NOT NULL PRIMARY KEY, label VARCHAR(64) NOT NULL ); INSERT INTO sample (id, label) VALUES (1, alpha), (2, beta), (3, gamma);fixture 通过 apply-sql.sh 以 stdin 方式灌入容器docker exec -i … psql -U postgres -d $BACKEND_DB -v ON_ERROR_STOP1 $SQL_FILE任何 SQL 错误都会因ON_ERROR_STOP1而中断执行并报错。六、统一入口poe e2e-local与 run.sh技能的唯一受支持入口是scripts/run.sh引擎 shim。它会导出引擎契约所需的环境变量后把控制权交给共享库编排脚本export CONNECTORsource-postgres export ENGINE_SCRIPTS_DIR$SKILL_DIR/scripts export DEFAULT_CONFIG_TEMPLATE$SKILL_DIR/fixtures/configs/base.template.json export DEFAULT_FIXTURE$SKILL_DIR/fixtures/sql/00-init-base.sql export BACKEND_NAME${BACKEND_NAME:-source-postgres-db-backend} exec $REPO_ROOT/airbyte-integrations/db-harness-lib/scripts/run.sh $这段 shim 同时也是 db-harness-lib README 中的最小引擎示例。它要求引擎必须导出CONNECTOR不带airbyte/前缀的镜像名、ENGINE_SCRIPTS_DIR含start-backend.sh/apply-sql.sh/reset-databases.sh、DEFAULT_CONFIG_TEMPLATE、DEFAULT_FIXTURE与BACKEND_NAME。在连接器根目录poe_tasks.toml 把poe e2e-local任务直接绑定到这个 shim并把命令行参数原样转发[tasks.e2e-local] help Run the local e2e harness end-to-end (backend, fixtures, spec/check/discover/read sweep, teardown). Arguments are forwarded to run.sh; … cmd ${POE_PWD}/.agents/skills/source-postgres-e2e-tests/scripts/run.sh因此实际使用方式为在连接器目录下运行cd airbyte-integrations/connectors/source-postgres # 单版本全量扫描 poe e2e-local --test-version3.8.5 # 目标 vs 对照对比非 CDC poe e2e-local --test-versiondev --control-version3.8.4 # 只跑 read 一个命令 poe e2e-local --commandread --test-version3.8.5run.sh会完整执行启动后端 → 应用 fixtures → 渲染配置 → 依次运行spec→check→discover→ 从 discover 输出派生 configured catalog → 运行read→ 退出时清理后端。七、协议扫描的执行细节7.1 完整命令集与参数run.shdb-harness-lib/scripts/run.sh支持的参数如下参数取值/默认说明--test-version镜像 tag默认dev被测镜像版本发布版本直接用 tag未合并代码用dev--control-versiontag对照镜像版本启用对比模式--commandall默认/spec/check/discover/read只运行单个命令或全量扫描--skip-read—只跑 spec/check/discover对应工作流的skip_read_action输入--skip-fixtures—不应用任何 fixtures直接对后端现有状态扫描--step-name自动派生产物子目录名默认形如sweep-version-vs-control--catalog路径显式指定 configured catalog跳过 discover 派生--state路径将保存的 state 文件作为--state-path传给 read 步骤--sync-modefull_refresh默认/incremental派生 catalog 的同步模式--cursor-field字段名incremental 模式下的游标字段--streams逗号分隔表名只选择指定流做派生 catalog--config-template路径覆盖默认配置模板--fixture路径可重复追加 SQL fixture--resetnone默认/fixture/backend两次镜像运行之间的重置策略--keep-backend—退出时保留后端容器--build—对dev镜像先执行:dockerBuildx构建--—之后的参数原样转发给airbyte-ops各协议命令的超时与工作流一致spec 30 分钟 / check 30 分钟 / discover 60 分钟 / read 180 分钟并可用TIMEOUT_MINUTES_{SPEC,CHECK,DISCOVER,READ}覆盖run.sh。产物默认落在/tmp/source-postgres-repro即$REPRO_OUT可通过REPRO_OUT环境变量改到其他位置。7.2 产物布局一次run.sh调用会把所有产物写到$REPRO_OUT/step-name/下run.shconfig.json渲染后的工作配置host 已替换为 bridge IPconfigured_catalog.json从 discover 输出派生的 configured catalogspec/、check/、discover/、read/各一个子目录分别存放对应命令的stdout.txt、stderr.txt、report.md与report.html。在--resetfixture|backend对比模式下各命令目录还会进一步嵌套control/与target/让两侧产物都能保留。7.3 扫描语义失败不中断汇总报告全量扫描时四个命令都针对同一个后端执行任何一个命令失败都不会中断后续命令——每个命令的结果都会被记录最后统一输出一张汇总表只要存在失败命令就以非零码退出。如果某次read之前discover已经失败read会被报告为SKIPPED而非ERROR因为 discover 没产出 catalog 时 read 根本无从运行见 run.sh。在 CI 环境下GITHUB_STEP_SUMMARY已设置汇总表还会追加到 GitHub 的步骤摘要中。若只运行单个命令则直接以连接器自身的退出码返回方便复现脚本继续断言。这里有一个重要的基础设施语义如果某个命令没有产出report.md会被判定为internal基础设施故障而不是测试失败——「运行根本没走到产出结论」与「运行了但断言失败」被刻意区分开避免把环境问题误读为回归run.sh。7.4 连接器退出码的获取run-protocol-cmd.sh 在单版本模式下会加--skip-compareTrue调用airbyte-ops。由于airbyte-ops的 CLI 在连接器非零退出时自身仍可能返回 0仅在 stderr 打印 Single-version regression test failed …脚本用set e包裹调用后从report.md中- **Exit Code:**行提取连接器的真实退出码返回给调用方。这保证了run.sh拿到的RC是连接器语义上的退出码而不是 CLI 的包装返回值。7.5 派生 configured catalogread需要的是configuredcatalog而discover输出的是普通AirbyteCatalog。手写 configured 形式最容易与 fixture 脱节而 catalog 漂移恰恰是 read 阶段出现 bad config 失败的常见原因因此 make-catalog.sh 会从真实的 discover 输出机械地派生用 jq 取出 stdout 中最后一个CATALOG消息的catalog.streams按STREAMS过滤默认全选为每个流填充sync_modefull_refresh或incremental、cursor_field、destination_sync_modeincremental 用append否则overwrite以及generation_id、minimum_generation_id、sync_id、destination_object_name、include_files等字段——这些字段不能为 null否则会被 bulk-CDK 的 schema 校验器拒绝该结论在 4.4.12 与 5.0.0 两个版本上都验证过is_file_based由脚本补为falsecursor_field无游标时补空列表primary_key取source_defined_primary_key。八、声明式期望替代 grep 断言与其在驱动脚本里手写grep -q substring || exit 1去检查命令产物run.sh提供了声明式期望参数在返回前强制执行SKILL.md 与 run.shFlag作用--expect-testpass\|fail目标侧整体结论target 全部命令通过才算 pass--expect-controlpass\|fail对比模式下对照侧结论要求同时指定--control-version且--resetfixture或--resetbackend--min-recordsN目标侧 read 必须至少包含 N 条RECORD消息--min-statesN目标侧 read 必须至少包含 N 条STATE消息--expect-match[command:]channel:regex[:N]目标侧指定命令输出必须至少匹配正则 N 次--forbid-match[command:]channel:regex目标侧指定命令输出不得匹配该正则匹配断言读取的是目标侧指定命令的产物未写命令前缀时默认是read。合法 channel 为stdout、stderr、any合法命令名为spec、check、discover、read。匹配规格的解析在 parse_match_spec只有开头的command:/channel:前缀会被识别只有结尾的:N会被剥离因此正则本身可以安全地包含冒号。--min-records/--min-states只针对 read 步骤它们统计的是 read 特有的RECORD/STATE信封见 count 逻辑。任何期望失败都会让脚本以非零码退出并写进汇总表的Expectation failures一节。例如把原来的 grep 断言改写成poe e2e-local --test-version3.8.5 --expect-matchstderr:expected message这条命令要求目标镜像 read 步骤的 stderr 中至少出现一次expected message。注意--expect-test与--min-*是独立于命令级结论的即使目标侧命令本身全部 pass只要期望未满足脚本仍会以退出码 1 结束——否则--expect-testfail --expect-match…这类用例中目标侧的非零退出码会「泄漏」成脚本自身的退出码掩盖期望是否真的匹配run.sh。九、对比模式用--control-version证明修复对比模式解决的核心问题是「这个修复是否真的改变了行为」。三种--reset策略对应不同的对比语义9.1--resetnone默认run.sh对每个命令同时传入--test-image与--control-image两个镜像顺序跑在同一个后端上由airbyte-ops内置的比较器record 数、主键、逐记录、schema产出目标 vs 对照的 diff。适合非 CDC 的 full-refresh 场景——此时 diff 既有意义又便宜。9.2--resetfixture先跑完对照侧完整扫描然后删除所有非系统数据库、重新应用 fixtures再跑目标侧扫描。产物落在$REPRO_OUT/step-name/{control,target}/command/。比--resetbackend快但数据库内部的递增时钟如 SQL Server 的 log-LSN不会重置所以逐记录的 LSN 列与 STATE 偏移在两侧会有差异。适合 CDC 对比——共享同一个捕获实例会污染 diff。9.3--resetbackend与--resetfixture相同但两次扫描之间会重建后端容器约多花 15 秒启动时间把 LSN 时钟一并重置。只有当复现依赖于两侧 LSN 序列完全一致时才需要用到。--reset在没有--control-version时无效并会打印警告避免静默忽略配置错误的调用见 run.sh它只控制两次镜像运行之间的重置单版本模式下不存在第二次运行。9.4 对比报告中的结论提取对比模式下run-protocol-cmd.sh 从report.md的**Result:**行判断结论出现REGRESSION DETECTED或Both versions failed即返回失败否则再解析| Target (行的退出码返回。这也解释了为什么对比报告没有单版本模式的- **Exit Code:**行——它把两个版本分别列在表格里。9.5 获取目标镜像对于推送了 PR 分支的代码优先使用已发布的镜像用 Airbyte Ops MCP 工具publish_connector_to_airbyte_registry从 PR 发布预发布版本然后把产出的version-preview.7位shatag 作为--test-version。这样挂架会直接拉取已发布的 tag完全跳过冷启动的 Gradle 构建也让评审者拿到一个可以复跑的 tag见 db-harness-lib README。仅当代码不在已推送的 PR 分支上时才需要本地构建要么先构建好airbyte/source-postgres:dev要么给run.sh传--build让它在--test-versiondev时自动执行./gradlew :airbyte-integrations:connectors:source-postgres:dockerBuildx --configure-on-demandrun.sh。十、常见坑Common gotchas以下为原文档明确列出的注意事项配合源码说明如下本技能不包含 CDC。生命周期以逻辑复制模式启动 PostgreSQL 16是为了让 source-postgres-e2e-cdc-tests 复用后端CDC fixtures 与用例脚本都在那个技能里。PostgreSQL 配置形状有特定要求本地明文后端必须ssl_mode.modeprefer标准同步的replication_method.methodStandard。如果配置用了 CDC 而派生 catalog 是 full_refreshrun.sh会直接拒绝exit 2并提示传入--sync-modeincremental --cursor-field… --streams…或--catalogPATH因为此时连接器配置不到任何 CDC 流read 会以误导性的 Saved offset no longer present 报错中止run.sh。连接器通过 bridge IP 解析后端render-config.sh把 IP 替换进每个渲染配置因为本地 regression-test 命令目前不接受--network。check失败可能以零码退出连接器可能一边输出失败的CONNECTION_STATUS一边以 0 退出CDK 的已知行为。当复现依赖 check 时的行为时必须对状态消息做断言用--expect-matchcheck:stderr:…之类而不是依赖退出码。严禁使用客户连接本挂架仅用于本地测试绝不能对客户连接或 Airbyte Cloud 使用。十一、清理与收尾共享库默认的 stop-backend.sh 是幂等的run.sh在EXITtrap 中默认会调用它清理后端容器若传了--keep-backend则保留容器并提示手动清理。手动清理方式BACKEND_NAMEsource-postgres-db-backend \ airbyte-integrations/db-harness-lib/scripts/stop-backend.sh rm -rf $REPRO_OUT unset REPRO_OUT如果引擎需要额外的清理卷、网络、sidecar可以提供引擎专属的stop-backend.sh放在ENGINE_SCRIPTS_DIRrun.sh会优先使用它否则回退到共享库默认实现run.sh。十二、小结一条可复用的本地回归流水线把以上内容串起来source-postgres-e2e-tests提供的是一条完整的本地回归流水线Docker 拉起固定版本的 PostgreSQL 16 → 应用幂等 SQL fixtures → 渲染 bridge-IP 配置 → 对任意镜像 tag 依次执行 spec/check/discover/read → 从 discover 机械派生 catalog → 声明式断言输出 → 汇总表 语义化退出码 → 幂等清理。配合--control-version的三种 reset 策略可以在不改动任何云端资源的前提下完成「复现 bug → 验证修复 → 对比回归」的完整闭环且连接器开发者无需 GSM 或 Cloud 管理凭据即可在本地独立完成。该技能还示范了一种可复用的仓库模式引擎相关脚本与 fixtures 留在连接器技能目录引擎无关的协议编排沉淀到db-harness-lib共享库后续其他数据库连接器只需提供一个十几行的 shim 即可获得同样的端到端测试能力。赞分享数据工程数据集成ETL后端大数据【免费下载链接】airbyteOpen-source data movement for ELT pipelines and AI agents — from APIs, databases files to warehouses, lakes, and AI applications. Both self-hosted and Cloud.项目地址https://gitcode.com/gh_mirrors/ai/airbyte点击查看免费下载相关推荐4步掌握B站视频下载高效获取4K大会员内容4步掌握B站视频下载高效获取4K大会员内容 还在为无法离线观看B站优质视频而烦恼吗bilibili downloader这款开源工具让你轻松下载B站视频包数据工程数据集成ETL后端大数据如何用PowerShell脚本快速打造轻量级Windows 11系统终极精简指南如何用PowerShell脚本快速打造轻量级Windows 11系统终极精简指南 你是否觉得Windows 11变得越来越臃肿每次开机都要等待几十秒磁盘空数据工程数据集成ETL后端大数据VisionCamera 真机 Harness 测试指南为命令式 API 编写端到端回归测试VisionCamera 真机 Harness 测试指南为命令式 API 编写端到端回归测试 导读 本文介绍 react native vision came移动开发音视频上一篇balance终极Python工具包轻松解决数据样本偏差难题下一篇【亲测免费】 探索Apple文件系统Linux上的APFS FUSE驱动创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考