Manage schema evolution in a fast-paced microservices environment

Official answer

Treat each service's database as an owned implementation detail where possible, and evolve published API/event contracts separately. Direct cross-service table access creates dependencies that must be discovered and migrated explicitly.

Test old readers with new writers and new readers with old writers, including historical events. Adding an optional field can be compatible, but type, unit, default, enum and semantic changes may still break consumers. A schema registry compatibility check cannot establish every business meaning.

Use expand–migrate–contract: introduce a compatible representation, deploy tolerant consumers/producers, backfill with version-aware handling of concurrent writes, switch consumers, then remove obsolete fields only after the deprecation window. Keep ownership, affected consumers and completion evidence visible.

Version migration artifacts and serialize their execution. Code history does not make a destructive data transformation reversible. Define rollback or forward repair based on stored data and new writes, not only application binaries. Rehearse lock/rewrite costs and partial failure with realistic data.

For events, retain decoding schemas and migration policy for replay. Test a mixed-version deployment and rollback before release, monitor consumer errors and lag, and coordinate removal rather than assuming independent deployments are automatically compatible.