Notesencoding🌱 seedling

Backward and Forward Compatibility

Also: Backward Compatibility · Forward Compatibility · Backwards Compatibility · Full Compatibility · Transitive Compatibility

Backward compatibility means new code can read data written by old code; forward compatibility means old code can read data written by new code. Which one a change preserves decides who must upgrade first.

Why it exists

Old and new versions overlap during every deploy, in every database and in every replayable log. The overlap is safe only if each side can read the other's data.

How it works

  • Backward (new reads old): needed for as long as old data exists. Easier, since the new code knows the old format.
  • Forward (old reads new): old code must skip additions it couldn't anticipate, and keep them if it writes back.
  • Full: both. Adding or removing only fields with defaults keeps it.
  • Transitive: check against every earlier version, not just the latest.
Change Backward Forward
add field with default ✓ ✓
add field without default ✗ ✓
remove field with default ✓ ✓
remove field old code requires ✓ ✗
reuse a Protobuf field number ✗ ✗

Trade-offs

Mode Upgrade order Cost
backward only readers (consumers) first producers wait for every consumer
forward only writers (producers) first old data may become unreadable to new code
full either side, any order the narrowest set of allowed changes

In practice

  • Schema registries default to BACKWARD so consumers can rewind a topic to the start.
  • Rollbacks need forward compatibility: rolled-back code must read what the new code wrote.

Pitfalls

  • Non-transitive checks when very old data still exists: v3 may read v2 but not v1.
  • Forgetting that a rolling deploy of a service that reads and writes shared data needs both directions.

Recall

These cards are also in your review deck, scheduled with spaced repetition.