DbMigrationChangeGuidelines

= DB Migration Change Guidelines =

We use sqlalchemy-migrate to enable step-wise and reversible changes to database schemata. (Note: Neutron uses Alembic.)

Given the centrality of schema migration to any OpenStack upgrade, it is important 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)
 * This practice also poses potential issues for deployers tracking trunk, so I propose we stop doing it. -- dhellmann
 * Just to clarify, it's not the compaction per se that's potentially problematic for trunk-chasers, more the risk that in manually compacting multiple scripts some regression will creep in due to human error? -- eglynn
 * trivial modifications to existing scripts that do not result in structural change
 * We need a concrete example of something that would meet these criteria and that could not also be accomplished with a new migration. -- dhellmann
 * An example would be say a downgrade that sanitizes a table of rows marked deleted, which in retrospect could be more selective of the data that it removes - so it could be improved to become more data-preserving, but the structural outcome would be identical. -- eglynn