Skip to content

History and baseline ​

The migration history table records versions alongside their filenames and hashes. Use it together with the actual schema to understand what has been applied.

Inspect status ​

sh
migrate status
migrate status --output json

The table reports Version, Filename, Hash and Status. JSON is useful for automation.

StatusMeaningNext step
pendingFile has not been appliedReview and run up
appliedVersion was successfully appliedKeep the file unchanged
baselineVersion was recorded without running itPreserve the adopted history
outOfOrderPending version is below the applied versionReview ordering policy
hashMismatchRecorded and current file hashes differRestore the historical file
filenameMismatchRecorded and current filenames differRestore the historical filename

Hash or filename mismatches block execution. Do not rewrite an applied migration to make a new schema change; add a higher version instead. Script checksums cover entry source bytes, not imported helpers; see Module reproducibility.

Baseline an existing database ​

Use baseline only when the database already matches the migration files being adopted. It records history without executing their SQL or scripts.

  1. Compare the existing schema and data with the migration files.
  2. Initialize the history table with migrate create if needed.
  3. Run migrate baseline, then inspect migrate status.
  4. Add a new higher version for future changes and apply it normally.

Baseline is not a repair command for a partially failed migration. First establish the real database state; blindly recording history can hide missing changes.