Keep database changes compatible during a release.

A new release can reach one application instance while the previous version is still running elsewhere. A database migration has to account for both.

Add a field the old version can ignore

In this simplified example, version 1.8 creates delivery records without a delivery_zone field. Version 1.9 introduces that field. The first database change adds it with null allowed. Version 1.8 can continue writing records, and version 1.9 must handle records whose zone is still missing.

Requiring a value at this stage would break the old writer. Filling existing records once would not prevent version 1.8 from creating more records with a missing zone while it remains active.

Old and new versions can overlap

The new field accepts null. Version 1.9 must handle a row that has no delivery zone.

A simplified compatibility example for a new delivery_zone field. It is not a deployment procedure for a particular application.

Stage	Database field	Application versions	Consequence
Add field	delivery_zone allows null	1.8 and 1.9	Version 1.8 ignores the field; 1.9 handles a missing value.
Retire old writers	delivery_zone still allows null	1.9 only	Finish the backfill and check for null values.
Require the value	delivery_zone cannot be null	2.0	Old writers that omit the value are incompatible.

A simplified compatibility example for a new delivery_zone field. It is not a deployment procedure for a particular application.

Finish the transition before tightening the constraint

After version 1.8 has left the service, complete the backfill for records that still lack a zone. Check scheduled jobs and other writers as well as the interactive application. Any continuing writer needs to supply the value before the database can require it.

A later release can apply the required-field constraint once those conditions hold. The application should also give a useful validation message when a zone has not been supplied. A database error alone is usually a poor instruction to the person completing the form.

Test rollback against the resulting database

After the constraint is applied, version 1.8 is no longer a suitable rollback target because it omits the required value. A compatible version 1.9 may still be usable if its writes supply the field and its other dependencies remain compatible.

The release record needs to identify that change in the rollback boundary. Reversing the application deployment does not reverse records written by the new version. Removing a column, transforming data or changing a value’s meaning can require additional recovery work.

A test environment should exercise the overlapping versions and the migration sequence, including a record created by an older writer during rollout. That exposes a different failure from testing the newest application against a database that was already fully migrated.

Release engineering services

Older jobs can preserve an older write shape

An old web instance is not the only possible writer. A queued job may contain data created before the deployment and execute after the new application starts. Its payload can still omit the newly required field.

Inspect the producers and consumers involved in the transition. The compatible stage may need to accept both payload shapes until the older work has drained or been deliberately transformed. Applying the database constraint first moves that missing-value problem into the job processor.

Worker lifetime and runtime boundaries