Data and configuration have separate migration contracts
A data migration changes records, schema, or format; a configuration migration changes how code receives settings, flags, credential references, or defaults. They may be related, but they should not be collapsed into one plan line: data has integrity and recovery concerns, while configuration has startup, scope, and secret-handling concerns.
Each change needs source/target representation, compatibility window, owner, sequencing, validation, and a backout or forward-fix strategy. If an operation is irreversible, that is a blocking decision, not a minor note.
Inventory and sequencing
| Surface | Inventory | Sequence | Validation |
|---|---|---|---|
| Schema | tables, columns, indexes, constraints | expand -> migrate -> contract | schema and integrity checks |
| Records | volume, formats, nulls, ownership | backfill in bounded batches | counts, invariants, representative reads |
| Configuration | keys, defaults, environments, flags | add compatible mapping -> switch -> remove old | startup and scenario checks |
| Secrets references | names/scopes, not secret values | provision before switch | presence/permissions without exposure |
| Recovery | checkpoint, backout, forward-fix | define before pilot | recovery evidence or HOLD |
Compatibility patterns and their boundaries
- expand-contract provides a coexistence window, but requires retirement criteria;
- dual-read/dual-write adds reconciliation and idempotency risk;
- a backfill must be resumable, observable, and limited in blast radius;
- versioned configuration must have an explicit default and safe unknown-key behavior;
- secrets are not copied into task specs, logs, templates, or evidence;
- a forward-fix may be safer than a backout for state that cannot be returned.
Verification before and after switching
- Compare the data/configuration inventory with the dependency graph and affected behavior flows.
- Define the compatibility window, allowed coexistence, and retirement point.
- Prepare validation for counts, invariants, reads, writes, startup, and representative scenarios.
- Run a pilot only when an owner and recovery path exist; mark unavailable checks Unknown.
- After the switch, compare behavior, integrity, and operational signals; do not remove the source path before exit criteria.
- Record GO, HOLD, rollback, or forward-fix as a separate decision with evidence.
Canonical lesson source · JavaRush
Open JavaRush material