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.
Connections
- Part of
- Schema Evolution
- Learn first
- Serialization
- Builds on this
- API Versioning
Recall
These cards are also in your review deck, scheduled with spaced repetition.