database-migration-safety

Renaming a column on live data requires an explicit migration, not db:push. Inspect the live schema first, write an idempotent script that renames the shape, then verify no old columns remain and confirm application code no longer references the old name.

Use db:push only for additive schema-only changes with no data transformation. Use an explicit migration when renaming fields, backfilling data, fixing duplicates, tightening constraints, or changing a contract that existing rows already violate.

Count duplicates first, then remove or consolidate them deterministically before adding the constraint. After the migration, verify the constraint exists and re-check that no duplicates remain, failing loudly if postconditions are not met.

An idempotent migration uses existence checks such as IF EXISTS or IF NOT EXISTS, verifies preconditions before modifying anything, and converges to the same final state on re-runs. It also guards with DATABASE_URL and skips safely on fresh databases.

The compatibility window was likely ignored. The schema changed safely while application code still assumes the old contract, so use an expand-verify-contract rollout where old code survives intermediate schema states before contracting.