1 号机和 3 号机的代理都生成了下一号迁移：两张 PR 各自全绿，合进 main 以后谁先跑？（中英切换）

Thursday, 09:00. The agent on machine-1 is doing "store money in cents": it renames Order.total to amount_cents, and makemigrations writes 0002_rename_total_order_amount_cents.py. At the same moment the agent on machine-3 is adding a VIP flag: a vip field on Customer, plus a backfill that marks VIPs with orders_order.total > 100000. Its file is 0002_customer_vip.py. Both agents branched from the same main, whose newest migration was 0001_initial, so both honestly wrote "I depend on 0001".

Each PR's CI is green: fresh database, run migrations, run tests, nothing odd. Machine-4 finishes reviewing machine-1's PR and merges at 09:40. Machine-5 reviews machine-3's PR; the green check is still on the page; it merges at 09:41. git reports no conflict — the two migrations are two different new files, and models.py changed in two different classes. Ten minutes later the deploy pipeline stops on migrate.

The question for this post: when agents on two machines each generate the next migration off the same main, and each PR is green alone, what actually happens after both merge, why branch CI cannot catch it, and where the gate belongs. It is the same family as /merge-train-on-machine-7/ ("green alone, red together"), with one extra layer: the outcome depends not only on the code but on the history the database has already walked.

Lab: three migration tools, one collision

I built three toy repos on this box and ran everything with real commands, not simulation: Django 6.1.3, Alembic 1.20.1 (SQLAlchemy + SQLite), and the official Flyway 10.20.1 command line (bundled JRE, SQLite). Each repo has an M0; two agent branches fork from M0 and each writes one migration.

Django is the loud one. Each branch passes migrate and makemigrations --check. After both merge, migrate fails with CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph: (0002_customer_vip, 0002_rename_total_order_amount_cents in orders), and helpfully adds To fix them run 'python manage.py makemigrations --merge'.

For an agent that hint is a trap. It sees an error and a fix command, so it runs the command. makemigrations --merge creates an empty 0003_merge_*.py that joins the two leaves; the graph is legal again. But machine-3's backfill still does SELECT ... WHERE total > 100000, and total has been renamed by machine-1. Result: a fresh DB fails with no such column: total; an environment that shipped machine-1's migration first fails the same way; only an environment that shipped machine-3's migration first succeeds. Same code; success depends on which migration that database ran first. I also swapped the order of the two dependencies inside the merge migration: migrate --plan did not change. On this version you cannot steer sibling order through the merge migration. The Django docs describe --merge in one line, "Enables fixing of migration conflicts". It fixes the graph, not the meaning.

Alembic comes in a loud and a quiet flavour. Both branches set down_revision = "a0001"; after merge, alembic heads lists two heads. alembic upgrade head refuses: Multiple head revisions are present for given argument 'head', as documented in the Alembic branches guide. The trouble is that the same message offers the way out — "or 'heads' for all heads". alembic upgrade heads does not error, so I built a case that does not error but computes the wrong thing: machine-1's b1111 flips closed orders created before 2026 to archived; machine-3's c3333 adds an archived_at column and backfills it for every archived order. Both migrations are correct; they just depend on each other's order, and that dependency is not in down_revision.

With five seed rows I ran three histories. Prod shipped machine-1 first, then upgrade heads only adds c3333: orders 1 and 2 get archived_at. Another environment shipped machine-3 first: orders 1 and 2 are NULL. A fresh CI database running upgrade heads applied c3333 before b1111 on this run: orders 1 and 2 are NULL. Three databases, not one error, green CI, and the data has already forked.

Flyway moves the failure from CI to production. With sequential numbers, both agents write V42__; after merge Flyway refuses: Found more than one migration with version 42. Loud, fails in CI. The standard answer to that pain is "use timestamp versions". I did: machine-1's migration is V20261108093000, machine-3's is V20261108091500 — generated earlier, merged later. Prod deployed the 09:30 one first; when 09:15 arrives, the default config fails migrate with Validate failed ... Detected resolved migration not applied to database: 20261108091500 and suggests -outOfOrder=true. Meanwhile CI's fresh DB sorts by version and reports Successfully applied 3 migrations — green. With outOfOrder=true prod runs too, and Flyway prints its own warning (outOfOrder docs): outOfOrder mode is active. Migration of schema "main" may not be reproducible. Prod ran 09:30→09:15; the fresh DB ran 09:15→09:30. Timestamps removed the name clash but not the ordering problem, and turned an error you could see in CI into one you only see in production.

Mechanism: branch CI checks a path production will never walk

A migration system is a directed graph. Each migration declares its parent; the database records which nodes it has visited. When an agent generates a migration on a branch, the graph only contains main's tip at that moment, so the declared parent is always M0's tip. Two parallel agents are two edges growing from the same node.

git merges text. Two new files do not conflict, so git calls the merge clean; the fork in the migration graph is invisible at the text level. Branch CI runs on a fresh database and validates "M0 + my migration". Production must walk "M0 + their migration + my migration", a path branch CI never saw. Even if you run tests on the merge result like the machine-7 merge clerk does, if those tests only use a fresh database, the Flyway timestamp case and the Alembic upgrade heads case are still green — a fresh database has no history, and history is exactly what breaks.

There is a quieter layer. Tools only know declared dependencies. Machine-3's backfill reads the column machine-1 renames; machine-1's archiving decides which rows machine-3 backfills. Neither fact lives in dependencies or down_revision. So "making the graph legal" (merge migrations, merge heads, outOfOrder) only silences the tool; nobody has decided the order between the two changes. The only real fix: make the late arrival actually sit after the earlier one, then re-read your own migration.

The fix: gate the merge result, bind the green check to main's SHA

I wrote migration_gate.py and ran all three repos through collide → refuse → re-parent → pass. It does five things:

1. Check the merge result. git worktree checks out current main, merges the PR head, and every check runs in that temporary tree — never on the branch alone.
2. Graph check. Alembic: exactly one alembic heads. Django: makemigrations --check --dry-run, plus counting leaves per app with MigrationLoader. Flyway: no duplicate versions, and every version the PR adds must be greater than main's newest — that rule exists for timestamp inversions.
3. Really migrate, along two histories. Once as "build the DB at main, seed it, then apply the PR" (prod-like) and once from scratch (CI-like). On Alembic I also compare the two data dumps; they must match.
4. Forbidden moves. A PR that adds a merge migration or edits a migration file already on main fails outright.
5. Record main's SHA in the result. At merge time merge_if_fresh.sh compares it with current main and refuses on mismatch.

Item 5 is the one people skip and the one that matters. In the lab both PRs ran the gate against M0 at 09:20 and both passed — at that moment the merge result really was clean. After machine-1 merged, main became M1; machine-3's PASS was computed on M0 and was void, but nothing on the page said so. merge_if_fresh.sh printed REFUSE agent3/archived-at: gate ran on main=f66a7cb, main is now d154256 -> re-run gate. Merging anyway on a scratch copy immediately produced two alembic heads. Re-running the gate gave two reasons: two heads, and a replay-parity diff showing exactly orders 1 and 2. That is what GitHub's "Require branches to be up to date before merging" and merge queue are for: not one more test run, but tying a test result to a specific main.

After the failure, machine-3's agent rebases on main and runs reparent_migration.py. Alembic: c3333's down_revision goes from a0001 to b1111. Django: 0002_customer_vip becomes 0003_customer_vip, depending on 0002_rename_total_order_amount_cents. Flyway: V42__add_region.sql becomes V43__add_region.sql. The gate passes, the PR merges, main has one head.

A pit I fell into myself: on the Django line, the first gate version only checked the graph. The renumbered 0003_customer_vip had a legal graph, so the gate let it through — while its backfill still read total. Once I added "really run migrate along both histories", that step failed twice: main-first and from-scratch both hit no such column: total. The agent changed the backfill to amount_cents, and only then did the gate pass. Re-parenting fixes order, not content. Its value is turning a history-dependent failure into the same deterministic failure everywhere, which forces the fix.

One last, very common scene: later, machine-2's agent decides the archive cutoff is wrong and edits b1111, already on main. Databases that ran b1111 will never run it again; fresh ones run the new version. The gate fails twice: "PR edits migration(s) that already exist on main", and a parity diff where order 2 is archived on one side and still closed on the other.

Cost: how strict to be

"Must be based on latest main" costs re-runs. I estimated it with a rough simulation (simulated, not measured on GitHub): three dev machines, 18 PRs a day, a quarter carrying migrations, 12-minute CI. Doing nothing yields about 7 overlapping gate windows between migration PRs per week, each a potential double head or duplicate number. Requiring latest main for every PR adds about 7 rebase+CI cycles a day. Requiring it only for PRs that touch migrations (a path-filtered required check) adds under 0.5 a day. For this team I recommend the third: a strict lane for migration PRs, everything else as before.

GitHub's merge queue automates this, but its documentation says it is only available for public repos owned by organizations, or private repos in organizations on GitHub Enterprise Cloud; and required checks must also listen to the merge_group event, otherwise the queue waits forever for a check that never reports. Where you cannot use it — a personal private repo, say — have the machine-7 merge clerk run migration_gate.py and compare SHAs before merging. Same effect, you maintain it yourself.

On naming: sequential numbers collide, timestamps do not. My conclusion is to keep sequential numbers. A collision is loud in CI. A timestamp inversion on Flyway is loud only in production. Alembic's random IDs never clash by name; the fork is loud only when someone runs upgrade head, and silent once they switch to upgrade heads. The goal of a naming scheme should not be "never conflict" but "conflicts must be visible before merge". With the gate's "new version must exceed main's newest" rule, either scheme is controllable, but sequential numbers let a human see the order at a glance.

When this does not fit

• Intentional multiple branches. Alembic supports branch labels and multiple bases; some teams want independent migration lines. Then "exactly one head" becomes "exactly one head per branch label".
• Several Django apps. Leaves are per app. Two agents touching different apps do not conflict and the gate will not block them, which is correct. Do not write a global "only one new migration" rule.
• Parity is only as good as the seed. My seed had five rows, which happened to cover the two rows that broke. Real projects need a small anonymised sample or a seed written for migrations; otherwise matching dumps do not mean matching meaning.
• Large data migrations. Running them twice in CI may be too slow. Split backfills into background jobs, keep migrations structural, and gate the structure.
• Declarative schema tools. If a schema-diff tool generates changes from a target state, there is no "next number", so naming and re-parenting do not apply; "validate on the merge result against a database with history" still does.

Rules for machines 1–3, and steps to copy tomorrow

The core of the AGENTS.md snippet for the dev machines is short. Before generating a migration, git fetch && git rebase origin/main, and generate it as the last step. Never edit a migration that is already on main. Never use makemigrations --merge, alembic merge heads, or -outOfOrder=true to turn CI green. When the gate reports multiple heads or an inversion, run reparent_migration.py, then re-read your migration, because it now runs after someone else's change. At most one migration-carrying PR per app per machine, labelled has-migration so machines 4 and 5 see it. No --admin merge past a failing gate.

Tomorrow, in order. First, put migration_gate.py in tools/ and run it locally against the migration PRs open right now, to see whether any have already collided. Second, add the kit's migration-gate.yml and make it a required check scoped to migration paths. Third, if you can use merge queue, enable it and confirm the merge_group trigger; if not, have machine 7 compare base_sha before merging. Fourth, write a seed for parity that covers the states you care about. Fifth, push the AGENTS.md rules to machines 1–3.

Honesty: what ran, what did not

Really ran on this box: Django 6.1.3, Alembic 1.20.1, and the Flyway 10.20.1 CLI (SQLite); every error message quoted is real output. Three full runs of collide → REFUSE → gate FAIL → re-parent → PASS → merge. Django still hitting no such column after --merge. Alembic's three-history data fork and parity diff. Flyway's timestamp inversion failing Validate on the "prod" DB while the fresh DB stays green. Editing an existing migration being blocked. The workflow YAML was only parsed for syntax.

Did not run: migration-gate.yml has never run on GitHub Actions, and merge queue / merge_group were not exercised. No seven-machine setup — "machine-1" and "machine-3" are branches on one box. The weekly collision count and extra CI runs come from a rough simulation. No PostgreSQL or MySQL; databases with different DDL transactionality may fail differently (MySQL DDL cannot roll back, so half-applied failures are messier).

Kit: parallel-agents-same-migration-number-kit.tar.gz — gate, re-parent script, merge_if_fresh.sh, workflow sample, AGENTS.md snippet, the three lab scripts, and full run logs.

One-line judgment: a migration PR's green check is only valid for the main it was computed on. Branch CI proves a path production will never walk. Put the gate on the merge result, run it against a database with history, and bind the green check to main's SHA. When main moves, run it again.