The migration was clean, but the schema lacked one thing: a new column.
Adding a new column sounds simple. It is not. In live systems with terabytes of data, a careless ALTER TABLE can lock rows for minutes or hours. Users notice. Transactions pile up. Latency grows. To add a new column without downtime, you need the right strategy.
First, know the database engine’s capabilities. In PostgreSQL, adding a nullable column without a default is fast because it only updates the metadata. Adding a column with a default rewrites the table unless you run it in two steps—create the column, then update in small controlled batches. In MySQL, ALTER TABLE may trigger a full table copy unless your version supports instant DDL. In distributed databases like CockroachDB, the new column will propagate across all nodes, and schema changes are asynchronous but still require monitoring.
Second, plan migrations to be repeatable and idempotent. Store them in version control. Use a tool that applies them in sequence and logs the results. Confirm you can run down migrations to roll back if needed. Use feature flags to control when the new column becomes visible to production traffic.