liveBook · Manning

Database migration

As explained in Grokking Software Architecture

A controlled change to a database's structure, such as its tables or columns.

A database migration is a controlled change to a database’s structure, such as adding or replacing a column. As application code evolves, version-controlled migration scripts describe how to upgrade or roll back the schema. Tools such as Flyway, Liquibase, and ORM migration engines help keep development and production schemas aligned. section 8.4.1

A growing to-do app

A task might start with a title and description. Adding due dates or priorities in a SQL database means changing the schema and running migrations. Frequent changes can become a cost when requirements are still moving quickly. section 8.2.1

A live migration can be like remodeling a house during a dinner party: old and new service versions may use the same database at once. A breaking change can cause errors or data divergence. Expand/Contract stages the change so both versions can coexist. section 13.3.3 section 13.4.3

For example, to replace customer_phone with phone_mobile:

  • Expand: Add phone_mobile alongside customer_phone; keep the old column available to existing services. section 13.4.3
  • Transition: Deploy code that reads the old column and writes both columns, while a background process backfills historical records. Use deterministic write ordering or optimistic concurrency locks to prevent competing versions from overwriting migrated data. section 13.4.3
  • Contract: Retire the old structure after active service instances have moved to the new schema logic and the data backfill is complete. section 13.4.3

Migrations also have an operational cost. With multiple database engines, deployment pipelines may need to coordinate versioned SQL migrations with document validation and index reindexing across environments. Weigh that overhead against the benefit of each additional engine. section 8.2.7

How Grokking Software Architecture covers it

How deep it goes
Defines version-controlled upgrades and rollbacks, then details Expand/Contract phases and concurrency risks without showing a complete migration script.
Examples
Uses a growing to-do app and a customer phone column replacement to illustrate schema changes.
What you can do after
Evaluate/understand how to stage a schema change while old and new service versions share a database.
How it connects
Connects migrations to schema evolution, canary deployments, backward compatibility, dual writes, and optimistic concurrency.

Also explained in

Compare how 3 books explain database migration →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.