expand-contract

Expand / contract

When a change cannot be proven reversible, do not argue about the risk. Restructure it into three changes that each can be.

The pattern turns one irreversible step into a sequence where every individual step is reversible and every intermediate state is deployable. That is the whole idea: at no point does a rollback of the application require a rollback of the database.

---

When to reach for it

Use it whenever the honest answer to "can I restore the prior bytes?" is no:

• dropping a column or a table
• renaming anything
• narrowing a type (bigint → int, text → varchar(n))
• a lossy UPDATE (see postgres-safety §3)
• adding a NOT NULL column to a populated table
• splitting or merging columns

---

The three phases

1. EXPAND — add the new shape alongside the old

Additive only. Nothing is removed and nothing is rewritten. The old readers and writers keep working untouched.

ALTER TABLE users ADD COLUMN tier text;    -- brief lock, no rewrite on PG 11+

Backfill in batches, then dual-write from the application so both columns stay correct.

Reversible? Yes — drop the new column. Nothing depended on it.

2. MIGRATE — move the readers

A code change, not a schema change. Readers switch to the new column one deployment at a time. Writers write both. Run a reconciliation query until the two columns agree for every row:

SELECT count(*) FROM users u
  JOIN subscriptions s ON s.user_id = u.id
 WHERE u.tier IS DISTINCT FROM s.plan_tier;    -- must be 0 before phase 3

Reversible? Yes — point the readers back. The old column is still authoritative.

3. CONTRACT — remove the old shape

Only once nothing reads the old column. Prove it, do not assume it:

• the blast-radius scan returns zero references in any deployed branch
• pg_stat_statements shows no query touching the column over a full business cycle
• the dual-write has been on long enough to cover every code path

ALTER TABLE users DROP COLUMN plan_name;