You're reading docs for Nextly Alpha. APIs may change between releases.

CLIError codes

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 run nextly 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:create refuses to record them. Delete one of them with its snapshot in meta/, the one not applied where one is, and run nextly migrate:create again: it writes that change after the other.
  • Nothing to record: where the configuration is already what the newest migration records, nextly migrate:create writes 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 in meta/. If their change is wanted, make it in the configuration and run nextly migrate:create again.
  • In CI, nextly migrate:check fails 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)

On this page

Was this page helpful?