safe-migration

Never rename directly. Add a new column, dual-write to both columns, backfill historical rows in batches, switch reads to the new column behind a feature flag, and drop the old column only after the new one is authoritative for a full release cycle.

Expand-migrate-contract splits every schema change into three deployments: expand adds the new structure alongside the old, migrate dual-writes and backfills then switches reads, and contract removes the old structure after the new one is authoritative.

Use CREATE INDEX CONCURRENTLY on PostgreSQL or ONLINE=ON on MySQL 8 and SQL Server so the table stays readable and writable. Monitor lock escalation during the build to catch blocking before it affects traffic.

Run backfills in small batches with LIMIT, pauses between batches, and idempotent logic so reruns are safe. Size the batch according to your replica lag budget and never update the whole table in a single transaction.

Additive changes are always safe: a new nullable column, a new table, or a new index created concurrently. Destructive changes like drops, renames, type changes, or adding NOT NULL must be split across multiple deployments.

Do not deploy a single ALTER TABLE that fully locks a large table, a migration coupled to the app deploy that cannot roll back independently, an irreversible step without a backup, or a backfill rewriting all rows in one transaction.