Zero-Downtime Database Migrations

This concept applies to all deployments of `pandurart` that involve database schema changes. Schema migrations are executed by the dedicated db-updater service using Liquibase ↑LIQUIBASE, which is the only component with write access to the schema.

Rolling updates and canary deployments require that old and new application versions run in parallel against the same database. A breaking schema change — such as renaming or removing a column — would cause one of the two versions to fail.

The solution is the Parallel Change pattern ↑PARALLEL-CHANGE, also known as Expand and Contract or Zero-Downtime Database Migration ↑EVODB. It decomposes every potentially breaking schema change into a sequence of fully backward-compatible steps.

1. 🔁 The Three-Phase Pattern

1.1. Phase 1 — Expand

The schema is extended in a backward-compatible way. New columns, tables, or indexes are added alongside the existing structures. No existing column is removed or renamed. The old application version continues to work unchanged.

Example Liquibase changeset — Expand
<changeSet id="2024-06-01-001-expand" author="migration">
    <!-- add new column; nullable so the old app can still INSERT without it -->
    <addColumn tableName="events">
        <column name="location_url" type="VARCHAR(2048)"/>
    </addColumn>
</changeSet>

1.2. Phase 2 — Migrate / Transition

A new version of the application is deployed. It writes to both the old and the new column simultaneously and reads from the new column. During the rollout window, old instances still write only to the old column, so both columns must be kept consistent.

If existing rows must be backfilled, a data-migration changeset can be executed once all old instances are drained:

Example Liquibase changeset — Backfill
<changeSet id="2024-06-01-002-backfill" author="migration">
    <sql>
        UPDATE events
           SET location_url = website
         WHERE location_url IS NULL
           AND website IS NOT NULL;
    </sql>
</changeSet>

1.3. Phase 3 — Contract

Once all application instances run the new version and the old column is no longer written to or read from, a follow-up deployment removes it.

Example Liquibase changeset — Contract
<changeSet id="2024-07-01-001-contract" author="migration">
    <dropColumn tableName="events" columnName="website"/>
</changeSet>
The Contract changeset is intentionally released in a separate deployment from the Expand changeset — never in the same release.

2. 🔄 Deployment Flow

db-migration-phases

3. ✅ Rules to Follow

✅

Always add new columns as nullable or with a default value in the Expand phase.

✅

Keep the Expand and Contract changesets in separate releases (separate Git tags / deployments).

✅

Execute db-updater before deploying the new application version.

✅

Ensure all old instances are terminated before running the Contract changeset.

✅

Each Liquibase changeset must be idempotent — never modify an already-applied changeset.

❌

Never rename a column directly — use Expand (add new) → Migrate → Contract (drop old).

❌

Never change the data type of an existing column in a single step.

❌

Never add a NOT NULL constraint without a default value while old instances are still running.

4. 🏷️ Naming Convention for Changesets

Changeset IDs follow the convention:

<ISO-date>-<sequence>-<phase>

Examples:

  • 2024-06-01-001-expand

  • 2024-06-01-002-backfill

  • 2024-07-01-001-contract

This makes the migration history self-documenting and allows teams to identify which phase a changeset belongs to at a glance.

5. ⚠️ Relationship to Canary and Rolling Deployments

During a canary deployment, both the old (v1) and the new (v2) application version process live traffic simultaneously. The database schema must be valid for both versions at the same time.

canary-db

The Expand phase is the enabler: it guarantees that both v1 and v2 are compatible with the current schema throughout the entire canary window.

6. 📚 Further Reading and References

  • ↑PARALLEL-CHANGE — Martin Fowler: ParallelChange — the canonical description of the pattern.

  • ↑EVODB — Martin Fowler & Pramod Sadalage: Evolutionary Database Design — the broader methodology behind schema evolution.

  • ↑REFACTORING-DB — Scott Ambler & Pramod Sadalage: Refactoring Databases — the reference book with a complete catalogue of database refactoring patterns.

  • ↑LIQUIBASE — Liquibase: official documentation for the migration tool used by db-updater.

  • ↑LIQUIBASE-ZDDT — Liquibase: Zero-Downtime Deployments with Liquibase.

  • ↑EXPAND-CONTRACT — Martin Fowler: Expand Contract — a concise summary of the two outer phases.