A migration file is permanent. Once it runs against production, you cannot take it back without writing another migration.
Yet most teams write migrations the way they write application code: open an editor, start typing columns, figure out constraints as they go. The result is schemas full of implicit decisions nobody documented — default values nobody questioned, nullability choices that haunt the codebase for years.
Writing a 30-minute schema spec before the migration forces those decisions into the open, where they can be reviewed, challenged, and agreed upon.
Why schemas deserve specs more than code does
Application code gets rewritten. Frameworks get swapped. The database schema outlives almost everything else in the stack. A column added in 2019 is still there in 2026 unless someone explicitly removed it — and removing columns from a production database is one of the riskiest operations a team can perform.
