The migration had run. But the data was still broken.
You missed one thing: the new column.
Adding a new column to a database table sounds simple. In production systems, it can be the turning point between stable growth and cascading failures. The schema change is more than a line of SQL — it is a shift in structure, constraints, indexes, and implicit expectations baked into code and downstream systems.
Before creating a new column, decide its exact type and constraints. Avoid nullable unless it is required. Set defaults when possible to prevent inconsistent data. Use explicit names—avoid abbreviations. Think about indexing, but do not index in the first migration if you can defer.
Run migrations in a controlled environment first. Use feature flags in your application to write to the new column before reading from it. For high-traffic systems, deploy schema changes in small, reversible steps. In PostgreSQL, ALTER TABLE ... ADD COLUMN is fast for low volumes, but on massive datasets, even schema metadata changes can lock your table.
Watch for replication lag when adding a column in systems with read replicas. Monitor errors in your application logs after deployment. The new column must be observed in metrics, not trusted blindly.
Document the change. Update ORM models, API contracts, and documentation in the same merge. Code that references the new column should be merged after the column exists but before it is populated in production.
The work is done when the column is live, the data is populated, queries run within budgeted latency, and no hidden dependencies remain. Then, and only then, should the migration branch be merged and the issue closed.
Want to see schema changes like adding a new column happen safely, with real-time feedback and no guesswork? Build and test it live on hoop.dev in minutes.