Liquibase and Zero-Downtime Deployments: Managing Schema Evolution Phases

Answer

Decouple additive and destructive schema work with Liquibase contexts and labels, and gate the destructive run on the CI/CD pipeline after application health checks. Liquibase has no built-in hook to wait for an application health check; the pipeline must control timing.

Confirmed facts

• Liquibase contexts filter changesets at update time. A changeset tagged context="additive" runs only when --contexts=additive is passed.
• Labels provide an independent metadata axis. A changeset can carry both a context and a label, e.g., label="phase:cleanup", and be filtered with --labels.
• Preconditions can verify schema state, e.g., column exists before drop, but cannot verify application readiness.
• Editing an already-executed changeset to add or change a context changes its checksum and can cause validation failures on databases where it is recorded in DATABASECHANGELOG.

Steps for this case

1. Tag changesets by phase.

   <changeSet id="1" author="team" context="additive">
     <addColumn tableName="orders">...</addColumn>
   </changeSet>
   <changeSet id="2" author="team" context="destructive" label="phase:cleanup">
     <dropColumn tableName="orders" columnName="old_flag" />
   </changeSet>
   

   Additive changes run on every deploy. Destructive changes are defined but remain pending.
2. Deploy additive schema with app rollout.

   liquibase update --contexts=additive
   

   Run this in the same pipeline stage as the new application version. The database now supports both old and new app versions.
3. Health check gate. Run application health checks, smoke tests, and traffic validation. Do not proceed until the new version is stable.
4. Run destructive cleanup after confirmation.

   liquibase update --contexts=destructive
   

   This executes only the cleanup changesets. Context and label matching is case-sensitive.

Verification

Before enabling destructive contexts in production, validate the split on a scratch database:

liquibase update-sql --contexts=additive

Inspect the generated SQL to confirm destructive statements are absent. After the health-check gate, compare DATABASECHANGELOG entries before and after the destructive run to confirm only the intended cleanup changesets executed.

Likely explanation vs practice

It is likely that contexts and labels are sufficient to prevent premature destructive execution without editing changelogs per environment. The confirmed limitation is that Liquibase will not wait for health checks itself; the orchestrator must enforce the two-phase run.

One diagnostic detail that changes the recommendation: are you running rolling updates where old application instances remain live during the rollout? If yes, destructive cleanup must wait until the last old instance is terminated, not just until the new version reports healthy.