event-versioning

To evolve event schemas safely, use backward-compatible changes like adding nullable fields with defaults, and implement upcasters to transform old event shapes to new ones during aggregate replay or projection builds.

The upcaster pattern transforms old event data shapes to new versions during aggregate replay or projection builds. You define upcasters and register them in your dependency injection container to handle versioned event deserialization.

Event versioning requires versioned event data classes and a Version discriminator for type and version deserialization. This allows the system to identify event versions and apply the correct upcaster transformations during replay.

Manage snapshot versioning and invalidation by choosing between lazy upcasting on read or controlled batch migration. This ensures snapshots remain compatible when event schemas change during aggregate replay.

Use lazy upcasting to transform old event shapes on read during aggregate replay, or choose controlled batch migration for systematic updates. The choice depends on your read patterns and how quickly you need all historical events converted.

For backward-compatible changes like adding nullable fields with defaults, you can rely on direct deserialization without upcasters. Upcasters are needed when event shapes change in ways that require transforming old event data to new structures.