event-type-migrations

Event Type Migrations

Chronicle stores events forever. When an event's schema must change, you write a migration rather than editing the original record — Chronicle auto-discovers migrations and applies them when reading old events.

You only need this once events of the prior shape exist somewhere you can't regenerate (a real environment's event log). Before that — in greenfield development with disposable data — rename event types and change schemas freely; a migration just adds dead code that hides the real schema in git log.

When you need it

• An [EventType] needs a new required property (adding it would break observers reading old events).
• A property is renamed; old events carry the old name.
• The event shape changes structurally.

Never add a nullable value type to an [EventType] to represent "absent on old events" — Chronicle's analyzer warns on nullable event members. Add a migration with a default instead.

Generations

Every [EventType] has a generation (starts at 1). Each schema change increments it. Chronicle routes stored events through the migration chain before delivering them to projections/reducers.

Generation 1 (stored) → Migration 1→2 → Migration 2→3 → Current (Generation 3)

Steps

1. Keep the prior record and bump the generation on the new one

Keep the old shape available to the migration as TPrevious. Mark the current record's generation with [EventType(generation: N)] as always, and mark the prior record with [EventTypeGenerationFor<TCurrent>(N-1)] instead of its own [EventType] — its event type id is then resolved from the current record's [EventType], so the two can never end up with mismatched ids:

[EventType(generation: 2)]
public record OrderPlaced(OrderId OrderId, Currency Currency);   // generation 2 (current)

[EventTypeGenerationFor<OrderPlaced>(1)]
public record OrderPlacedV1(OrderId OrderId);   // generation 1 (prior)

Older style, still supported: you can instead give OrderPlacedV1 its own [EventType("order-placed", generation: 1)], as long as the id string is explicit and identical to the id on OrderPlaced. This is not deprecated, but prefer [EventTypeGenerationFor<T>] for anything new — an omitted or mismatched id on this older style silently defaults to the CLR type name, which Chronicle then treats as a wholly unrelated event type, and the migration never applies. Two analyzers (CHR0037, CHR0049) and a constructor-time exception (MigrationGenerationsMustShareEventTypeId) catch this mistake for both styles.