How do you change a database schema without breaking the running app?

Say it in 30 seconds

Say it like this (20-30 seconds)

I use an expand-and-contract change: add a compatible schema first, deploy code that can use it, backfill if needed, then remove old fields in a later release. MiniTickets runs migrations in one dedicated Fargate task before rolling the app. That ordering avoids every API replica migrating at startup, but it also means new schema changes must remain compatible with the old application still serving traffic.

The deeper answer

A migration is a deployment of shared state. Reverting an application image does not undo its SQL, copied data or lock impact. Review both forward compatibility with the old app and rollback compatibility with the retained image.

The migration runner validates database settings, uses a single connection and applies the SQL migration directory through Drizzle. The deployment script starts an on-demand Fargate task, waits for it to stop and reads the actual container exit code. Missing exit codes and nonzero codes are failures.

Before a large production change, estimate table size, lock duration, index strategy and backfill pace. A nullable additive column differs greatly from a rewrite of a hot table. This repository’s small development migration path does not prove those changes are safe at production scale. If the job fails, inspect the recorded migration state and the actual database state before choosing a rerun or repair.

Counter-questions

Why not migrate on API startup?

Multiple replicas could race, and a slow migration would couple application availability to startup. One explicit runner gives deployment a clear success or failure boundary.

Can you safely rerun every failed migration?

Only after checking what committed. Migration bookkeeping handles completed migrations; external effects or manually changed schema still require investigation.

Would you automatically reverse SQL on rollback?

No. Destructive reverse operations can lose new writes. Prefer compatibility and a reviewed forward repair.

Where in MiniTickets

Read the path chapter, select the relevant map piece →, then inspect infra/src/compute/migration-task.ts → createMigrationTask. Work through the related case for a diagnostic example.