moonbranch

    Build reproducible, referentially closed PostgreSQL test data branches.

    postgresql
    fixtures
    testing
    reproducibility
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Last updated
    6 hours ago
    Downloads
    3

    No dependencies

    #MoonBranch · 可复现的 PostgreSQL 测试数据分支

    从一条业务记录出发,把复现问题需要的关联数据做成可校验、可重放的制品。用同一份制品在本机、CI 或迁移验证环境中恢复相同的测试输入。

    JSON 配方 + PostgreSQL 一致性快照 → 根记录 + 外键闭包 + 显式子表扩展 → 带 SHA-256 的 JSON 制品 → 空的、已迁移的开发数据库

    • 故障复现:以发生故障的一笔订单为根,保留它的客户和明细,排除同一客户的其他订单。
    • PR 回归测试:在 CI 中固定同一份小型测试数据,避免测试依赖共享数据库里的实时内容。
    • 迁移验证:把同一制品分别写入施加了旧版和新版迁移的临时库,检查约束兼容性,再运行自己的业务测试。

    #安装与快速开始

    需要 MoonBit CLI、Node.js ≥ 22.4、PostgreSQL 和 psql。项目已在 PostgreSQL 18.6 上实测;CI 配置覆盖 16 和 18。

    git clone https://github.com/zlhahaha/MoonBranch.git cd MoonBranch moon build --target js --release cmd/main node bin/moonbranch.mjs --help

    用本地开发 PostgreSQL 演示。以下命令假定当前连接用户可创建数据库,且两个库名尚未使用。用 libpq 的 PGHOST、PGPORT、PGUSER、PGPASSFILE 等配置连接;不要把密码写入配方。

    createdb moonbranch_demo_source createdb moonbranch_demo_target psql -X -v ON_ERROR_STOP=1 -d moonbranch_demo_source -f examples/shop/schema.sql -f examples/shop/seed.sql psql -X -v ON_ERROR_STOP=1 -d moonbranch_demo_target -f examples/shop/schema.sql MOONBRANCH_SOURCE=moonbranch_demo_source node bin/moonbranch.mjs capture examples/shop/recipe.json shop.branch.json node bin/moonbranch.mjs verify shop.branch.json MOONBRANCH_TARGET=moonbranch_demo_target node bin/moonbranch.mjs restore shop.branch.json psql -X -d moonbranch_demo_target -c 'SELECT tenant, id FROM shop.orders;'

    PowerShell 中用 $env:MOONBRANCH_SOURCE = 'moonbranch_demo_source' 或 $env:MOONBRANCH_TARGET = 'moonbranch_demo_target' 单独设置环境变量,再运行相同的 node 命令。

    示例恢复 1 位客户、1 笔订单、2 件明细。电子邮件替换成测试值,联系备注置空。verify 离线校验摘要、引用闭包和遮盖规则。restore 核对目标表和外键,以一个事务恢复;任一步失败会回滚。输出路径已存在时,capture 拒绝覆盖。

    #MoonBit 库

    moon add zlhahaha/moonbranch@0.1.0

    在调用方 moon.pkg 引入 "zlhahaha/moonbranch" @branch。parse_spec、parse_dataset 读取输入;slice 和 verify_branch 不依赖数据库连接。需要接入自己的 PostgreSQL 客户端时,可用 capture_sql、check_capture_size 和 restore_sql。完整签名见 公开接口。Node 只负责进程、文件和 SHA-256。

    #范围与数据处理

    • 首版面向已有经批准的开发或预生产样本库。配方显式声明表、列、主外键、根、子边和遮盖项。capture 不会自动查找个人信息;未遮盖字段、主键和根键仍可能敏感。制品经审查后再共享。SHA-256 用于检测内容意外变更,不能代替签名或加密。
    • 每张表最多读取 50,000 行,CLI 每个进程输出及制品限 64 MiB。max_rows 限制结果,不会截断外键闭包。大型数据库请先准备更小的来源;首版没有流式采集、云数据库分支或持续同步。
    • 支持同一 schema 普通表、受支持的主键类型及指向声明主键的 MATCH SIMPLE 外键。目标库须先执行应用迁移,指定表为空。首版不搬运 DDL,不重置序列,不运行目标用户触发器。详细配方与兼容性。

    #验证与出处

    moon fmt --check moon check --deny-warn moon test --deny-warn moon build --target js --release --deny-warn cmd/main # 仅在隔离的测试实例使用;测试账户需要 CREATEDB。 node scripts/integration.mjs

    集成测试覆盖一致性、关联范围、遮盖、篡改检测、外键变化、重复恢复拒绝与事务回滚。设计与相近项目。许可证:Apache-2.0。

    BranchError

    pub(all) suberror BranchError {
    Invalid(String)
    }

    capture_limit

    let capture_limit : Int

    capture_sql

    fn capture_sql(spec : Spec) -> String raise BranchError

    Read each declared table in one consistent snapshot. Masked columns are replaced in PostgreSQL before any source value reaches the client.

    check_capture_size

    fn check_capture_size(data : Dataset) -> Unit raise BranchError

    parse_dataset

    fn parse_dataset(text : String) -> Dataset raise

    parse_spec

    fn parse_spec(text : String) -> Spec raise

    restore_sql

    fn restore_sql(spec : Spec, data : Dataset) -> String raise BranchError

    Generate a transaction for an empty, pre-migrated development database.

    slice

    fn slice(spec : Spec, data : Dataset) -> Dataset raise BranchError

    Roots and opted-in descendants can expand downward. Rows included only to satisfy a foreign key cannot bring in unrelated rows below them.

    validate

    fn validate(spec : Spec) -> Unit raise BranchError

    verify_branch

    fn verify_branch(spec : Spec, data : Dataset) -> Unit raise BranchError