A zero-downtime DynamoDB GSI migration pattern: versioned, alternating indexes

A backend pattern from production work at Razroo that I rarely see written up: AWS won't let you update an existing DynamoDB Global Secondary Index. To add a returned attribute, you have to delete and recreate it — and recreation triggers a full backfill that re-indexes every row, often 5–10 minutes depending on table size. That's a real problem if you have live APIs in dev and production depending on that index.

The fix is to treat GSIs as versioned, immutable resources. Instead of mutating user-index in place, build user-index-v2 alongside it. Once the new version is live across dev, test, and production, swap the template variable in your CloudFormation to point at it, then delete the old index. No maintenance window, no interrupted developers, production stays at 100% uptime.

The broader principle: alternating versioned resources beat in-place mutation when the platform won't give you safe updates.