Event Upcasters vs. Versioned Event Types for Rollback-Safe Schema Evolution

Schema Evolution in Akka Persistence

When updating the event schema for a Persistent Actor, the primary goal is ensuring that a previous binary version can still recover state if a deployment must be rolled back after new events have been written to the journal.

The Compatibility Constraint

Akka Persistence provides EventAdapter and upcaster chains to handle forward compatibility, allowing newer code to interpret legacy events. However, Akka does not provide a native "downcasting" mechanism. If a new binary writes events with added fields or changed structures, an older binary may fail to deserialize these events during replay, leading to actor recovery failure.

Design Trade-offs

Two common patterns exist to mitigate this risk:

• Additive Schema Evolution: Using optional fields with default values in the serialization layer to ensure older binaries ignore unknown properties.
• Versioned Event Types: Introducing distinct event classes (e.g., UserUpdatedV2) and maintaining separate reader logic for both versions during the transition period.

While additive changes simplify the event stream, snapshots created by the new binary may remain opaque binary blobs that are incompatible with the old binary, potentially bypassing event-level compatibility.

Technical Questions

Does the use of versioned event types provide a more reliable rollback path than additive optional fields when snapshots are involved? How should the snapshot version be decoupled from the event schema to prevent recovery failures during a binary rollback?