The database migration that should have been two migrations

A database migration that both changes the schema, adding a column, renaming a table, and transforms existing data to fit the new shape, in a single migration script is a common shortcut that saves a bit of time upfront and removes the option to cleanly roll back if something goes wrong partway through either the schema change or the data transformation.

The problem surfaces specifically during a failure: if the combined migration fails halfway, the database is left in a state that's neither the old schema with old data nor the new schema with new data, a genuinely difficult state to reason about or recover from cleanly, especially under the time pressure of a production incident.

Splitting the same change into two migrations, one that changes the schema in a backward-compatible way, a second, separate migration that transforms the data once the schema change is confirmed stable, means each step can be independently verified and rolled back if needed, without ever leaving the database in an ambiguous intermediate state.

This costs a small amount of extra planning time per migration and consistently pays for itself the first time a migration needs to be rolled back under pressure, which is precisely the moment a combined, all-or-nothing migration becomes a much harder problem than it needed to be.