Two feature branches each add a migration numbered V37 and both merge in the same week. What problems does that cause, and how do teams keep migration ordering sane when many people work in parallel?

## Why the number matters A versioned migration tool applies pending scripts in version order and records what it applied. That works perfectly on a single linear history. Branching breaks the assumption: each branch extends the same linear sequence independently, so both authors reach for the next free number, and the trunk ends up with two claims on it. ## Failure one: duplicate versions Flyway treats a duplicate version as a hard error and refuses to run — annoying but safe, because it surfaces at build time. Liquibase, keyed on `id + author + filename`, will not report a duplicate at all; both changesets simply execute, in changelog-inclusion order. That is safer against collision but shifts the risk to the *master changelog* file, which becomes the merge conflict point instead. ## Failure two: out-of-order arrival Suppose branch A merges first as `V37`, branch B is renumbered to `V38`, and everything is fine. Now consider the opposite ordering in the wild: - Alice's laptop ran her own `V37` (branch A) days ago. - Branch B merges and its script keeps the number `V37` under a different name. - Alice pulls. Flyway sees a *new* script whose version is not greater than the highest applied version, and by default fails with an "out of order" error; with `outOfOrder=true` it applies it, but her database's applied sequence is now A-then-B while CI's fresh build is B-then-A. If the two migrations are genuinely independent, both orders yield the same schema and the divergence is harmless. If one depends on the other — B adds a foreign key to a table A created, or both alter the same column — the orders are not equivalent, and one of the two environments is silently wrong or the migration fails only in some environments. This asymmetry is what makes the problem a senior-level topic: the mechanical collision is easy, the semantic one is not. ## Fix one: allocate the version as late as possible The collision exists because two people picked the number at *branch start*. Two ways to move the decision to merge time: - **Timestamp versions.** `V20260812_1030__add_orders_status.sql`. Two developers colliding requires the same second. Ordering follows wall-clock authoring time, which is not the same as merge time, but it is deterministic and unique. This is the most common answer. - **Renumber on merge.** Keep sequential numbers but make it the merging author's job to move their file to the next free number and re-run migrations locally. Cheap in a small team, error-prone in a large one. A repository convention that puts each migration in its own file with a globally unique name (and a CI check that fails on duplicate versions) turns a production incident into a red pull request. ## Fix two: make ordering not matter The deeper fix is designing migrations so that any interleaving with concurrently developed migrations is valid: - Each migration touches its own objects and does not depend on another in-flight migration. - Additive first: add a table, add a nullable column, add an index. Additive changes commute with almost anything. - If two changes genuinely must be sequenced, they belong in the *same* migration or the *same* branch, merged together. When migrations commute, out-of-order application is a non-event and you can safely enable out-of-order mode for developer environments. ## Fix three: prove it in CI Two pipelines catch the two shapes of failure: 1. **Build from empty.** Every merge creates a database from nothing and replays the whole migration history. This catches duplicates, broken SQL, and dependency-order bugs in the canonical ordering. 2. **Replay onto a snapshot.** Restore a recent production-shaped dump (schema, sanitised data) and apply only the pending migrations. This catches the case that only breaks against real prior state — a `NOT NULL` added to a column that has nulls in production, a unique index that real data violates, a migration that takes 40 minutes on 200 million rows. Running both on every pull request, not just on the release branch, is what makes parallel development safe. ## Liquibase-specific note Because Liquibase includes changelog files from a master changelog, the merge conflict lands in that master file rather than in the numbering. The convention that avoids daily pain is one changelog file per release or per change, `include`d in date order, with `logicalFilePath` set so a later file move does not change a changeset's identity and cause it to re-run. ## Never do this Renumbering a migration that has *already been applied* somewhere shared. For Flyway the version is part of the identity, so changing it makes the script look pending again and it re-executes; for Liquibase, changing the file path or id has the same effect unless `logicalFilePath` pins it.