How to Rename a Column Safely (Add, Backfill, Switch, Drop)

An in-place rename breaks old code instantly, so rename by adding a new column, backfilling, switching reads, and dropping the old one later.

A single RENAME COLUMN is a breaking change: the old app version queries the old name and errors the moment the migration lands. The safe sequence spans releases: add the new column, dual-write, backfill, switch reads to the new column, then drop the old one.

The four moves

• Add: create the new column (nullable).
• Backfill: copy existing values in batches and dual-write from code.
• Switch: deploy code that reads the new column.
• Drop: remove the old column in a later release.

Add and backfill

ALTER TABLE users ADD COLUMN email_address text;
-- app dual-writes email -> email_address; backfill the rest:
UPDATE users SET email_address = email
WHERE email_address IS NULL AND id BETWEEN 1 AND 10000;

Gotchas

• Keep dual-writing until every running version reads the new column.
• Do not skip the backfill; new reads would miss rows written before the new column existed.

Related guides