magnus919_agent-skills/migration-engineering/references/compatibility-patterns.md

Compatibility Patterns

Detailed patterns for forward and backward compatibility by migration type. Load this reference when designing the compatibility surface for a specific migration.

Schema compatibility

Forward compatibility (old readers, new writers)

Old readers must be able to consume data written by the new schema. This is the more common constraint: you control the writer deployment but cannot upgrade every reader simultaneously.

Patterns:

• Add columns as nullable or with defaults. Old readers ignore unknown columns.
• Never rename a column in place. Add the new column, dual-write both old and new names during the compatibility window, then drop the old column after all readers have migrated.
• Never change a column type in place. Add a new column with the target type, dual-write to both, migrate readers, backfill the new column from the old, then drop the old column.
• Use views or computed columns to present a stable interface while the underlying schema changes.

Backward compatibility (new readers, old writers)

New readers must be able to consume data written by the old schema. This applies when readers are deployed before writers or when you cannot control writer upgrade order.

Patterns:

• New readers treat new columns as optional. Missing columns must not cause errors.
• New readers must handle the old enum values, old units, old precision.
• Consider a compatibility adapter layer that translates old-format data to new-format before it reaches the new reader.

Data compatibility

Dual-write patterns

Both old and new stores receive writes during the transition.

Patterns:

• Synchronous dual-write: Write to both stores in the same transaction or unit of work. Strong consistency; adds latency and a failure mode (what if one write succeeds and the other fails?).
• Asynchronous dual-write: Write to the primary store, then publish an event that the secondary store consumes. Eventual consistency; the secondary store lags behind the primary. Acceptable when the lag is bounded and monitored.
• Change-data-capture (CDC): The secondary store tails the primary's write- ahead log or change stream. No application code change; the CDC pipeline must be monitored for lag and errors.

Dual-read patterns

Both old and new stores are read during the transition for comparison.

Patterns:

• Shadow read: Read from the new store in parallel with the old store; compare results; use the old store's result for the response. Log mismatches.
• Percentage read: Route a configurable percentage of reads to the new store. Increase over time as confidence grows.
• Consumer-driven read: Individual consumers opt into reading from the new store. Track per-consumer migration status.

API compatibility

Additive changes (safe)

• Adding a new endpoint or field.
• Adding an optional query parameter.
• Adding a new enum value (if consumers handle unknown values gracefully).
• Adding a new response header.

Breaking changes (require compatibility window)

• Removing an endpoint, field, or enum value.
• Renaming a field or endpoint.
• Changing a field type or response shape.
• Changing authentication requirements.
• Changing error response format.
• Changing rate limits downward.

For breaking changes, use the expand/contract pattern: add the new interface alongside the old, give consumers a migration window, track consumer migration, then remove the old interface.

Infrastructure compatibility

Network continuity

• DNS migration: lower TTL before the change, dual-publish old and new records during the transition, verify propagation before removing old records.
• Certificate rotation: deploy new certificates before old ones expire; both old and new certificates must be valid during the overlap window.
• Service discovery: register the new service instance before deregistering the old one.

Data-plane continuity

• Database connection strings: dual-configure applications with both old and new connection parameters; switch via configuration, not code deploy.
• Message broker migration: dual-publish to old and new brokers; dual-consume during the transition; verify no message loss before shutting down the old broker.