The migration was almost done when the data model broke. The fix needed a new column.
Adding a new column should be simple. Yet in real systems, it touches migrations, indexes, queries, and API contracts. Done wrong, it slows queries, corrupts data, or takes production down. Done right, it becomes a clean extension to the schema with zero downtime.
Start with the schema change. Use an explicit migration file. Define the new column with the correct type and constraints from the start. Avoid nullable columns unless undefined values are truly valid. In relational databases like PostgreSQL or MySQL, adding a column with a default can lock the table. For large tables, add the column without a default, backfill in batches, then add the default and constraints.
Update all queries that need the new column. Search for SELECT * and replace it with explicit columns. This prevents silent behavior changes. For write operations, ensure that inserts and updates include the correct data for the new column.