Field guide 05

A column rename is a breaking API change between your schema and your fleet.

During a rolling deploy, old and new application versions run at once. An additive compatibility window is safer than asking every process to switch names atomically.

The risky shapes

ALTER TABLE users
  RENAME COLUMN name TO display_name;

ALTER TABLE users
  DROP COLUMN legacy_name;
Release verdict: BLOCK when old code or rollback releases still reference the old column.The SQL may finish quickly, but application compatibility can fail immediately and the drop creates a data-recovery boundary.

An additive rename sequence

1. Add the replacement

ALTER TABLE users
  ADD COLUMN display_name text;

2. Deploy compatibility

Write both columns or establish one authoritative source with reliable synchronization. Read the new column with a fallback while old rows and old processes remain.

3. Backfill and reconcile

UPDATE users
SET display_name = name
WHERE id > :last_id
  AND id <= :next_id
  AND display_name IS NULL;

SELECT count(*)
FROM users
WHERE display_name IS DISTINCT FROM name;

4. Switch and observe

Switch reads to the new column, confirm old versions and jobs are drained, stop old writes, and observe error rates plus data reconciliation through the rollback window.

5. Contract later

ALTER TABLE users
  DROP COLUMN name;

Keep the contract migration separate and explicitly approved. Inventory views, functions, generated columns, triggers, exports, ETL, replicas, and ad hoc consumers before removal.

Evidence gate

  • Every application version, worker, job, view, function, and external consumer is inventoried.
  • Dual-write ordering and retry behavior cannot produce divergent values silently.
  • The backfill is bounded and reconciliation reaches zero unexplained differences.
  • Rollback code continues to understand both schema shapes.
  • Backup retention and restore timing cover the post-drop recovery requirement.

Rollback boundary

The additive phase preserves both representations, so reads can return to the old column. The drop is the point of no return for an ordinary application rollback. After it, recovery depends on retained source data, a backup, or a separately tested reconstruction path.

Primary references