migrate-guard

Detect and auto-renumber colliding sqlx migration version numbers across git branches.

sqlx assigns a migration's version at author time, so two branches that both add NNNN_*.sql at the same NNNN merge cleanly, then fail at test time with UNIQUE constraint failed: _sqlx_migrations.version. migrate-guard catches this before merge and renumbers your topic branch above the global max.

A collision is one version number claimed by two different files (e.g. 0002_a.sql and 0002_b.sql). The same migration file present on multiple branches is not a collision.

Install

cargo install migrate-guard

Configure — migrate-guard.toml at the repo root

base_ref = "main"
reference_globs = ["src/**/*.rs"]

[[dir]]
role = "platform"
path = "migrations"

[[dir]]
role = "tenant"
path = "crates/kernel/migrations_tenant"

Each [[dir]] is an independent numbering namespace: the same version number in two different roles is not a collision.

Use

cargo migrate-guard check                 # CI gate: non-zero exit on collision
cargo migrate-guard renumber              # dry run: show the plan
cargo migrate-guard renumber --apply      # renumber this branch's new files + rewrite include_str! refs
cargo migrate-guard max                   # print the max version per role

renumber only ever touches the files THIS branch adds (working-tree files absent from base_ref), numbering them above the max seen across base_ref, every other local branch, and the rest of the working tree. It renames with git mv and rewrites exact-filename references (e.g. include_str!) in reference_globs.

CI

- run: cargo install migrate-guard
- run: cargo migrate-guard check

License

Licensed under either of MIT or Apache-2.0 at your option.