A database migration can succeed technically while breaking the application version still serving users. Plan schema changes around the period when old and new code may both be active.
For a small SaaS, the safest design is often to separate adding a new shape, moving data, changing application behaviour, and removing the old shape. The exact steps depend on the database version and migration tool, so verify them in the actual environment.
Define compatibility before writing the migration
List the code paths that read and write the affected fields: web requests, workers, scheduled jobs, exports, integrations, and support tools. Record which application versions may run during deployment or rollback.
Review the operation's locking and transaction behaviour in the documentation for your installed database. The PostgreSQL documentation is a starting point, but a current manual may differ from the version you operate.
Rehearse a fictional status-field migration
Suppose a request table has a free-text status and the product needs a reviewed set of workflow states. Start by adding the new representation while preserving compatibility. Define a mapping for known values and a review path for unknown legacy values.
Backfill in a controlled way and count mapped, unmapped, and invalid records. Do not silently force every unknown value into “new,” because that changes business meaning. Test active requests arriving while the backfill runs and decide how both representations remain consistent during transition.
Switch reads and writes only after the compatibility conditions are met. Verify ordinary editing, exports, background processing, and rollback to the prior application version. Remove the old representation only when no supported code still depends on it.
Treat recovery as more than reversing a file
A reverse schema migration may not restore information lost through a transformation. Preserve an appropriate recovery path and test it with fictional data. If the new application writes values the old one cannot understand, rollback needs a data decision as well as a deployment decision.
Choose an observation window and owner for post-change checks. Compare record counts, invalid states, failed operations, and representative user workflows. A clean migration command exit is only one part of the evidence.
The tradeoff is deployment complexity versus interruption risk. Multi-step changes take more planning and leave temporary compatibility code. A small low-risk table may support a simpler maintenance window. Decide from data volume, customer commitments, and tested behaviour rather than applying one ritual to every change.
The StackFlight case study provides SaaS database context. This status migration is fictional and includes no executable migration or performance claim.
Questions about live database changes
Must every migration use several releases?
No. Match the process to compatibility and failure impact. Explain why a simpler change is safe in the actual operating context.
Is a backup enough for rollback?
A backup helps recovery but may involve downtime and loss of later writes. Test the recovery method against the product's requirements.
What should a release review include?
Include version compatibility, legacy-value mapping, lock considerations, verification, and recovery ownership. Bring the transition plan to a migration review.