Defines an expand-migrate-contract database workflow with compatibility windows, lock and resource budgets, resumable backfills, verification, guarded cutover, and roll-forward recovery.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Deploy backward-compatible schema expansion before code depends on it, migrate data with an idempotent checkpointed job, cut reads/writes through observable gates, and remove old structures only after rollback compatibility expires.
Scope
- Migration ownership, schema changes, compatibility, locking, backfill, dual behavior, verification, cutover, rollback, contract cleanup, and evidence.
- Relational production databases with rolling application deployments.
- Online and maintenance-window profiles.
Outside this block
- Pretending every DDL operation is online on every database/version.
- Using down migrations as the primary recovery for destructive production changes.
Contract
- Each migration declares database/version assumptions, estimated table size, lock class, transaction behavior, resource budget, owner, and recovery plan.
- Expansion is readable by old code and writable by the chosen compatibility path.
- Backfills are idempotent, bounded, checkpointed, rate-limited, and distinguish untouched from intentionally null data.
- Dual-write or translation has a named authority and reconciliation; two fields never become indefinite independent truth.
- Cutover gates include data parity, error, latency, replica lag, and application-version coverage.
- Contract changes occur only after the rollback window and evidence that no supported code uses the old schema.
Implementation guidance
- Inspect generated SQL and database documentation for the exact engine/version before approval.
- Use a migration lock so only one runner applies a version; keep application startup independent from long backfills.
- Create indexes with the engine's supported online/concurrent method and account for its transaction restrictions.
- Prefer roll-forward repair and restore-tested backups for destructive failure.
Failure handling and safeguards
- If lock acquisition exceeds budget, abort without waiting indefinitely.
- If backfill error, lag, or load crosses a threshold, pause safely at a durable checkpoint.
- If cutover fails, switch authority back while both representations remain compatible; do not drop data.
Verification and operations
- Measure lock wait/duration, statement duration, rows and errors per batch, replica lag, parity mismatch, cutover errors, and old-field reads/writes.
- Rehearse on production-like size and inspect query plans.
- Record migration, application, and schema versions for incident correlation.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.