MIGRATION_HISTORY_FORKED
Migrations were written without each other, and no migration yet records them together, so the command applied none of them that was not applied already.
Cause
Migrations were written without each other, and no migration yet records them together, so the command applied none of them that was not applied already.
Each migration is written from the one before it: nextly migrate:create compares the configuration with the newest snapshot, and the new migration's snapshot records which migration that was (parent). A migration accounts for its parent and everything before it. Two migrations that do not account for each other were written without each other, and each knows nothing of the other's changes. It happens in two ways:
- Two branches each added a migration, and were merged. This is the common one.
- Two writers ran at once. One writer of migration files runs at a time (see
MIGRATIONS_WRITER_BUSY), but a command stopped for longer than its hold, on a suspended laptop for example, can write beside the one that took its place.
Until a migration written with all of them in the folder records them together (its snapshot names the other branch's end in merges), the newest snapshot lacks one side's changes. A migration that only follows one of the branches records nothing. nextly migrate, a production start, nextly migrate:check and a Schema Builder save refuse the history and name the files, and nextly migrate applies nothing further. Where one is already applied on the database the command reads, the message says which, and names the other as not applied.
A blank migration (nextly migrate:create --blank) has no snapshot, so it states the migration it was written after in its header (-- Parent:, and -- Merges: where it records a merge). Two blank migrations written without each other are refused in the same way.
Migrations written before parents were recorded, and snapshots copied by hand for a hand-written migration, name no parent and are never refused.
Fix
- The branches change different things (the message says to record the merge): run
nextly migrate:create --name record_merge. It writes a migration after both that records the merged state, and the history is one line again. Then runnextly migrate. - Blank migrations (the message says to record that they apply in this order): run
nextly migrate:create --blank --name record_merge, which writes a blank migration after them that names both; or delete one where they do the same thing. Their SQL is yours, so nothing compares what they change. - The branches change the same thing (the message names the table or column both change; an index or key on a column counts as a change to that column): they cannot be applied one after the other, since each was written against it as it stood before the other, and
nextly migrate:createrefuses to record them. Delete one of them with its snapshot inmeta/, the one not applied where one is, and runnextly migrate:createagain: it writes that change after the other. - Nothing to record: where the configuration is already what the newest migration records,
nextly migrate:createwrites nothing and names the migrations written without it. That is the same change written twice (a command that was stopped and one that took its place), or a change the merged configuration no longer has: delete the migrations it names, each with its snapshot inmeta/. If their change is wanted, make it in the configuration and runnextly migrate:createagain. - In CI,
nextly migrate:checkfails until the merge is recorded, so a merge that needs one is caught on the pull request.
Example
✗ Two migrations were written from 20261020_120000_add_posts.sql: 20261021_090000_add_tags.sql and 20261021_090500_add_price.sql.
Why: 20261021_090000_add_tags.sql is applied on this database, and 20261021_090500_add_price.sql was written without its changes, so it was not applied.
Next: Run `nextly migrate:create --name record_merge` to record the merge.
Docs: https://nextlyhq.com/docs/cli/errors/migration-history-forked (MIGRATION_HISTORY_FORKED)