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
migrate status
migrate status --output jsonThe table reports Version, Filename, Hash and Status. JSON is useful for automation.
| Status | Meaning | Next step |
|---|---|---|
pending | File has not been applied | Review and run up |
applied | Version was successfully applied | Keep the file unchanged |
baseline | Version was recorded without running it | Preserve the adopted history |
outOfOrder | Pending version is below the applied version | Review ordering policy |
hashMismatch | Recorded and current file hashes differ | Restore the historical file |
filenameMismatch | Recorded and current filenames differ | Restore 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.
- Compare the existing schema and data with the migration files.
- Initialize the history table with
migrate createif needed. - Run
migrate baseline, then inspectmigrate status. - 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.