Ship a Database Rename Without Breaking Old Code

A column rename takes a moment in a migration file. In a rolling deployment, old workers may still read the original name while new workers expect the replacement. The migration must account for the period when both versions are alive.

Expand the schema first

Suppose display_name will become public_name. Add the new nullable column while keeping the old one. Deploy code that still reads the old value and maintains both fields on every relevant write. Inventory background workers, imports and administrative scripts. One forgotten writer can reintroduce divergence long after the web rollout is complete.

During the mixed-version period, old binaries may update only the old field. Either coordinate an explicit compatibility mechanism at the database boundary or wait until every old writer has drained before treating the new field as authoritative.

Backfill without overwriting fresher values

Work in bounded batches and record progress. Design the operation to be repeatable. A condition such as “new field is null” prevents some overwrites but does not repair a stale non-null value left by an old writer. Establish the source of truth for this phase, reconcile differences and verify counts on representative records.

Handle null semantics deliberately: a legitimate null is different from a row not yet migrated. A progress marker or a separate reconciliation query may be necessary.

Contract after the rollback window

Switch reads to the new field only after the compatibility checks pass. Monitor errors and mismatches. Keep the old field populated for as long as rolling back to an old binary is a supported response. Remove the old field in a later deployment after proving there are no remaining readers or writers. The reversible period ends when the old code can no longer find the data it expects.

Further reading

Martin Fowler: Parallel Change

Related guide: Move a Website Without Losing New Orders.