Why your migration looked fine locally and stalled in staging

Staging is not “production with fewer users.” It is often production with different maintenance windows, colder caches, and scripts that nobody reran since last quarter. When a migration that flew on a laptop crawls in staging, start by comparing lock modes and statement timeouts—not just row counts.

We ask teams to capture EXPLAIN (ANALYZE, BUFFERS) in both environments when feasible, with identical parameter settings. A missing index in staging is a classic culprit, but so is autovacuum lag that leaves heap bloat invisible in local docker volumes. Second, verify extensions and collation versions; subtle planner shifts show up as “random” slowdowns.

Finally, document the rollback path before you celebrate the forward migration. A reversible series of DDL steps buys calm during incident calls. In Wave Blaze labs, students attach a one-page decision log to each migration PR; it is boring paperwork until it saves a Friday evening.