DbMigrationChangeGuidelines

DB Migration Change Guidelines

We use sqlalchemy-migrate to enable step-wise and reversible changes to database schemata.

Given the centrality of schema migration to any OpenStack upgrade, it is improtant that all projects agree on what type of changes to the migration scripts should be allowed or red-flagged in reviews.

Invariants

• DB schemas must always be migrate-able across milestone releases
• migrations must be structurally reversible, but not necessarily data-preserving

Aspirational

• migration should also be maintained across individual commits, to avoid causing unnecessary issues for trunk-chasing deployments

Unacceptable changes

• re-ordering of migration indices
• modificationss to existing scripts that could cause later migrations to fail (ruling out pretty much any structural change)

Acceptable changes

• compaction of adjacent scripts, coinciding with major releases (as per the nova practice over the last couple cycles)
• trivial modifications to existing scripts that do not result in structural change