Event Type Migrations

Event type migrations enable you to evolve your event schemas over time while maintaining compatibility with existing events. When an event type changes, you can define upcasters and downcasters that automatically transform events between different generations.

Why Migrations?

In evolving systems, event schemas naturally change:

• Properties are added or removed
• Properties are renamed
• Complex properties are split or combined

Chronicle’s migration system allows you to:

1. Define declarative transformation rules
2. Automatically store all generations of an event when appending
3. Read events in any generation format

Defining Migrations

To define a migration, extend the EventTypeMigration<TUpgrade, TPrevious> base class (it handles generation extraction and validation for you) and override Upcast/Downcast:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Migrations;

[EventType("author-registered", generation: 2)]
public record MigrationsAuthorRegistered(string FirstName, string LastName);

[EventTypeGenerationFor<MigrationsAuthorRegistered>(1)]
public record MigrationsAuthorRegisteredV1(string Name);

public class MigrationsAuthorRegisteredMigration : EventTypeMigration<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1>
{
    public override void Upcast(IEventMigrationBuilder<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1> builder) =>
        builder.Properties(pb => pb
            .Split(m => m.FirstName, e => e.Name, PropertySeparator.Space, SplitPartIndex.First)
            .Split(m => m.LastName, e => e.Name, PropertySeparator.Space, SplitPartIndex.Second));

    public override void Downcast(IEventMigrationBuilder<MigrationsAuthorRegisteredV1, MigrationsAuthorRegistered> builder) =>
        builder.Properties(pb => pb
            .Combine(m => m.Name, PropertySeparator.Space, e => e.FirstName, e => e.LastName));
}

Kotlin

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.events.migrations.EventTypeMigration
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "author-registered", generation = 2)
data class MigrationsAuthorRegistered(val firstName: String, val lastName: String)

@EventType(id = "author-registered", generation = 1)
data class MigrationsAuthorRegisteredV1(val name: String)

class MigrationsAuthorRegisteredMigration :
    EventTypeMigration<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1>(
        MigrationsAuthorRegistered::class,
        MigrationsAuthorRegisteredV1::class
    ) {
    override fun upcast(builder: EventTypeMigrationBuilder<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1>) {
        builder
            .split(MigrationsAuthorRegistered::firstName, MigrationsAuthorRegisteredV1::name, " ", 0)
            .split(MigrationsAuthorRegistered::lastName, MigrationsAuthorRegisteredV1::name, " ", 1)
    }

    override fun downcast(builder: EventTypeMigrationBuilder<MigrationsAuthorRegisteredV1, MigrationsAuthorRegistered>) {
        builder.combine(MigrationsAuthorRegisteredV1::name, " ", MigrationsAuthorRegistered::firstName, MigrationsAuthorRegistered::lastName)
    }
}

Java

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.events.migrations.EventTypeMigration;
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "author-registered", generation = 2)
record MigrationsAuthorRegistered(String firstName, String lastName) {
}

@EventType(id = "author-registered", generation = 1)
record MigrationsAuthorRegisteredV1(String name) {
}

class MigrationsAuthorRegisteredMigration
        extends EventTypeMigration<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1> {
    MigrationsAuthorRegisteredMigration() {
        super(MigrationsAuthorRegistered.class, MigrationsAuthorRegisteredV1.class);
    }

    @Override
    public void upcast(EventTypeMigrationBuilder<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1> builder) {
        builder
            .split("firstName", "name", " ", 0)
            .split("lastName", "name", " ", 1);
    }

    @Override
    public void downcast(EventTypeMigrationBuilder<MigrationsAuthorRegisteredV1, MigrationsAuthorRegistered> builder) {
        builder.combine("name", " ", "firstName", "lastName");
    }
}

Elixir

defmodule MyApp.Events.MigrationsAuthorRegisteredV1 do
  use Chronicle.Events.EventType, id: "author-registered", generation: 1

  defstruct [:name]
end

defmodule MyApp.Events.MigrationsAuthorRegistered do
  use Chronicle.Events.EventType, id: "author-registered", generation: 2

  defstruct [:first_name, :last_name]
end

defmodule MyApp.Migrations.MigrationsAuthorRegisteredMigration do
  use Chronicle.Events.Migration,
    from: {MyApp.Events.MigrationsAuthorRegisteredV1, generation: 1},
    to: {MyApp.Events.MigrationsAuthorRegistered, generation: 2}

  alias Chronicle.Events.MigrationBuilder

  @impl true
  def upcast(builder) do
    builder
    |> MigrationBuilder.split_property(:name, :first_name, " ", 0)
    |> MigrationBuilder.split_property(:name, :last_name, " ", 1)
  end

  @impl true
  def downcast(builder) do
    builder
    |> MigrationBuilder.combine_properties([:first_name, :last_name], :name, " ")
  end
end

TypeScript

import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
class MigrationsAuthorRegisteredV1 {
    constructor(readonly name: string) {}
}

@eventType('author-registered', 2)
class MigrationsAuthorRegistered {
    constructor(
        readonly firstName: string,
        readonly lastName: string
    ) {}
}

@eventTypeMigration(MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1)
class MigrationsAuthorRegisteredMigration implements IEventTypeMigration<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1> {
    upcast(builder: IEventMigrationBuilder<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1>): void {
        builder.properties(pb => pb
            .split('firstName', 'name', ' ', 0)
            .split('lastName', 'name', ' ', 1));
    }

    downcast(builder: IEventMigrationBuilder<MigrationsAuthorRegisteredV1, MigrationsAuthorRegistered>): void {
        builder.properties(pb => pb
            .combine('name', ' ', 'firstName', 'lastName'));
    }
}

The previous generation, MigrationsAuthorRegisteredV1, carries [EventTypeGenerationFor<MigrationsAuthorRegistered>(1)] instead of its own [EventType]. The event type id it resolves to comes straight from MigrationsAuthorRegistered’s own [EventType] — it is never independently typed on the previous-generation record, so the two generations cannot drift apart by a hand-typed, mismatched id.

The old style still works

You can still put an explicit, matching [EventType("id", generation: N)] on every generation — this is fully backward compatible, not deprecated. But both ids must be identical, explicit strings. Omit the id on a previous generation and it silently defaults to the CLR type name ("MigrationsAuthorRegisteredV1"), which Chronicle then treats as an entirely unrelated event type — the migration never applies, and registration fails at kernel startup with a confusing EventTypeSchemaChanged error. [EventTypeGenerationFor<T>] removes this failure mode structurally, which is why it is the recommended default for any new previous generation.

Migration Operations

The migration builder supports the following operations:

Split

Splits a source property into parts using a separator:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Migrations;

[EventType("person-registered", generation: 2)]
public record MigrationsSplitPersonRegistered(string FirstName, string LastName);

[EventTypeGenerationFor<MigrationsSplitPersonRegistered>(1)]
public record MigrationsSplitPersonRegisteredV1(string FullName);

public class MigrationsSplitPersonRegisteredMigration : EventTypeMigration<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1>
{
    public override void Upcast(IEventMigrationBuilder<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1> builder) =>
        builder.Properties(pb => pb
            .Split(m => m.FirstName, e => e.FullName, PropertySeparator.Space, SplitPartIndex.First) // Gets first part
            .Split(m => m.LastName, e => e.FullName, PropertySeparator.Space, SplitPartIndex.Second)); // Gets second part

    public override void Downcast(IEventMigrationBuilder<MigrationsSplitPersonRegisteredV1, MigrationsSplitPersonRegistered> builder) =>
        builder.Properties(pb => pb
            .Combine(m => m.FullName, PropertySeparator.Space, e => e.FirstName, e => e.LastName));
}

Kotlin

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.events.migrations.EventTypeMigration
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "person-registered", generation = 2)
data class MigrationsSplitPersonRegistered(val firstName: String, val lastName: String)

@EventType(id = "person-registered", generation = 1)
data class MigrationsSplitPersonRegisteredV1(val fullName: String)

class MigrationsSplitPersonRegisteredMigration :
    EventTypeMigration<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1>(
        MigrationsSplitPersonRegistered::class,
        MigrationsSplitPersonRegisteredV1::class
    ) {
    override fun upcast(builder: EventTypeMigrationBuilder<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1>) {
        builder
            .split(MigrationsSplitPersonRegistered::firstName, MigrationsSplitPersonRegisteredV1::fullName, " ", 0) // Gets first part
            .split(MigrationsSplitPersonRegistered::lastName, MigrationsSplitPersonRegisteredV1::fullName, " ", 1) // Gets second part
    }

    override fun downcast(builder: EventTypeMigrationBuilder<MigrationsSplitPersonRegisteredV1, MigrationsSplitPersonRegistered>) {
        builder.combine(MigrationsSplitPersonRegisteredV1::fullName, " ", MigrationsSplitPersonRegistered::firstName, MigrationsSplitPersonRegistered::lastName)
    }
}

Java

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.events.migrations.EventTypeMigration;
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "person-registered", generation = 2)
record MigrationsSplitPersonRegistered(String firstName, String lastName) {
}

@EventType(id = "person-registered", generation = 1)
record MigrationsSplitPersonRegisteredV1(String fullName) {
}

class MigrationsSplitPersonRegisteredMigration
        extends EventTypeMigration<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1> {
    MigrationsSplitPersonRegisteredMigration() {
        super(MigrationsSplitPersonRegistered.class, MigrationsSplitPersonRegisteredV1.class);
    }

    @Override
    public void upcast(
            EventTypeMigrationBuilder<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1> builder) {
        builder
            .split("firstName", "fullName", " ", 0)  // Gets first part
            .split("lastName", "fullName", " ", 1);  // Gets second part
    }

    @Override
    public void downcast(
            EventTypeMigrationBuilder<MigrationsSplitPersonRegisteredV1, MigrationsSplitPersonRegistered> builder) {
        builder.combine("fullName", " ", "firstName", "lastName");
    }
}

Elixir

defmodule MyApp.Events.MigrationsSplitPersonRegisteredV1 do
  use Chronicle.Events.EventType, id: "person-registered", generation: 1

  defstruct [:full_name]
end

defmodule MyApp.Events.MigrationsSplitPersonRegistered do
  use Chronicle.Events.EventType, id: "person-registered", generation: 2

  defstruct [:first_name, :last_name]
end

defmodule MyApp.Migrations.MigrationsSplitPersonRegisteredMigration do
  use Chronicle.Events.Migration,
    from: {MyApp.Events.MigrationsSplitPersonRegisteredV1, generation: 1},
    to: {MyApp.Events.MigrationsSplitPersonRegistered, generation: 2}

  alias Chronicle.Events.MigrationBuilder

  @impl true
  def upcast(builder) do
    builder
    # Gets first part
    |> MigrationBuilder.split_property(:full_name, :first_name, " ", 0)
    # Gets second part
    |> MigrationBuilder.split_property(:full_name, :last_name, " ", 1)
  end

  @impl true
  def downcast(builder) do
    builder
    |> MigrationBuilder.combine_properties([:first_name, :last_name], :full_name, " ")
  end
end

TypeScript

import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
class MigrationsSplitPersonRegisteredV1 {
    constructor(readonly fullName: string) {}
}

@eventType('person-registered', 2)
class MigrationsSplitPersonRegistered {
    constructor(
        readonly firstName: string,
        readonly lastName: string
    ) {}
}

@eventTypeMigration(MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1)
class MigrationsSplitPersonRegisteredMigration implements IEventTypeMigration<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1> {
    upcast(builder: IEventMigrationBuilder<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1>): void {
        builder.properties(pb => pb
            .split('firstName', 'fullName', ' ', 0) // Gets first part
            .split('lastName', 'fullName', ' ', 1)); // Gets second part
    }

    downcast(builder: IEventMigrationBuilder<MigrationsSplitPersonRegisteredV1, MigrationsSplitPersonRegistered>): void {
        builder.properties(pb => pb
            .combine('fullName', ' ', 'firstName', 'lastName'));
    }
}

Combine

Combines multiple source properties into a single value using a separator:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Migrations;

[EventType("shipping-address-recorded", generation: 2)]
public record MigrationsCombineShippingAddressRecorded(string FormattedAddress);

[EventTypeGenerationFor<MigrationsCombineShippingAddressRecorded>(1)]
public record MigrationsCombineShippingAddressRecordedV1(string Street, string City);

public class MigrationsCombineShippingAddressRecordedMigration : EventTypeMigration<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1>
{
    public override void Upcast(IEventMigrationBuilder<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1> builder) =>
        builder.Properties(pb => pb
            .Combine(m => m.FormattedAddress, PropertySeparator.Space, e => e.Street, e => e.City)); // Joins with space separator

    public override void Downcast(IEventMigrationBuilder<MigrationsCombineShippingAddressRecordedV1, MigrationsCombineShippingAddressRecorded> builder) =>
        builder.Properties(pb => pb
            .Split(m => m.Street, e => e.FormattedAddress, PropertySeparator.Space, SplitPartIndex.First)
            .Split(m => m.City, e => e.FormattedAddress, PropertySeparator.Space, SplitPartIndex.Second));
}

Kotlin

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.events.migrations.EventTypeMigration
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "shipping-address-recorded", generation = 2)
data class MigrationsCombineShippingAddressRecorded(val formattedAddress: String)

@EventType(id = "shipping-address-recorded", generation = 1)
data class MigrationsCombineShippingAddressRecordedV1(val street: String, val city: String)

class MigrationsCombineShippingAddressRecordedMigration :
    EventTypeMigration<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1>(
        MigrationsCombineShippingAddressRecorded::class,
        MigrationsCombineShippingAddressRecordedV1::class
    ) {
    override fun upcast(builder: EventTypeMigrationBuilder<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1>) {
        // Joins with space separator
        builder.combine(
            MigrationsCombineShippingAddressRecorded::formattedAddress,
            " ",
            MigrationsCombineShippingAddressRecordedV1::street,
            MigrationsCombineShippingAddressRecordedV1::city
        )
    }

    override fun downcast(builder: EventTypeMigrationBuilder<MigrationsCombineShippingAddressRecordedV1, MigrationsCombineShippingAddressRecorded>) {
        builder
            .split(MigrationsCombineShippingAddressRecordedV1::street, MigrationsCombineShippingAddressRecorded::formattedAddress, " ", 0)
            .split(MigrationsCombineShippingAddressRecordedV1::city, MigrationsCombineShippingAddressRecorded::formattedAddress, " ", 1)
    }
}

Java

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.events.migrations.EventTypeMigration;
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "shipping-address-recorded", generation = 2)
record MigrationsCombineShippingAddressRecorded(String formattedAddress) {
}

@EventType(id = "shipping-address-recorded", generation = 1)
record MigrationsCombineShippingAddressRecordedV1(String street, String city) {
}

class MigrationsCombineShippingAddressRecordedMigration
        extends EventTypeMigration<MigrationsCombineShippingAddressRecorded,
                                   MigrationsCombineShippingAddressRecordedV1> {
    MigrationsCombineShippingAddressRecordedMigration() {
        super(MigrationsCombineShippingAddressRecorded.class, MigrationsCombineShippingAddressRecordedV1.class);
    }

    @Override
    public void upcast(EventTypeMigrationBuilder<MigrationsCombineShippingAddressRecorded,
                                                 MigrationsCombineShippingAddressRecordedV1> builder) {
        // Joins with space separator
        builder.combine("formattedAddress", " ", "street", "city");
    }

    @Override
    public void downcast(EventTypeMigrationBuilder<MigrationsCombineShippingAddressRecordedV1,
                                                   MigrationsCombineShippingAddressRecorded> builder) {
        builder
            .split("street", "formattedAddress", " ", 0)
            .split("city", "formattedAddress", " ", 1);
    }
}

Elixir

defmodule MyApp.Events.MigrationsCombineShippingAddressRecordedV1 do
  use Chronicle.Events.EventType, id: "shipping-address-recorded", generation: 1

  defstruct [:street, :city]
end

defmodule MyApp.Events.MigrationsCombineShippingAddressRecorded do
  use Chronicle.Events.EventType, id: "shipping-address-recorded", generation: 2

  defstruct [:formatted_address]
end

defmodule MyApp.Migrations.MigrationsCombineShippingAddressRecordedMigration do
  use Chronicle.Events.Migration,
    from: {MyApp.Events.MigrationsCombineShippingAddressRecordedV1, generation: 1},
    to: {MyApp.Events.MigrationsCombineShippingAddressRecorded, generation: 2}

  alias Chronicle.Events.MigrationBuilder

  @impl true
  def upcast(builder) do
    builder
    # Joins with space separator
    |> MigrationBuilder.combine_properties([:street, :city], :formatted_address, " ")
  end

  @impl true
  def downcast(builder) do
    builder
    |> MigrationBuilder.split_property(:formatted_address, :street, " ", 0)
    |> MigrationBuilder.split_property(:formatted_address, :city, " ", 1)
  end
end

TypeScript

import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
class MigrationsCombineShippingAddressRecordedV1 {
    constructor(
        readonly street: string,
        readonly city: string
    ) {}
}

@eventType('shipping-address-recorded', 2)
class MigrationsCombineShippingAddressRecorded {
    constructor(readonly formattedAddress: string) {}
}

@eventTypeMigration(MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1)
class MigrationsCombineShippingAddressRecordedMigration implements IEventTypeMigration<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1> {
    upcast(builder: IEventMigrationBuilder<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1>): void {
        builder.properties(pb => pb
            .combine('formattedAddress', ' ', 'street', 'city')); // Joins with space separator
    }

    downcast(builder: IEventMigrationBuilder<MigrationsCombineShippingAddressRecordedV1, MigrationsCombineShippingAddressRecorded>): void {
        builder.properties(pb => pb
            .split('street', 'formattedAddress', ' ', 0)
            .split('city', 'formattedAddress', ' ', 1));
    }
}

Rename

Renames a property from a previous name using RenamedFrom:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Migrations;

[EventType("payment-processed", generation: 2)]
public record MigrationsRenamePaymentProcessed(decimal Amount);

[EventTypeGenerationFor<MigrationsRenamePaymentProcessed>(1)]
public record MigrationsRenamePaymentProcessedV1(decimal OldAmount);

public class MigrationsRenamePaymentProcessedMigration : EventTypeMigration<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1>
{
    public override void Upcast(IEventMigrationBuilder<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1> builder) =>
        builder.Properties(pb => pb
            .RenamedFrom(m => m.Amount, e => e.OldAmount));

    public override void Downcast(IEventMigrationBuilder<MigrationsRenamePaymentProcessedV1, MigrationsRenamePaymentProcessed> builder) =>
        builder.Properties(pb => pb
            .RenamedFrom(m => m.OldAmount, e => e.Amount));
}

Kotlin

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.events.migrations.EventTypeMigration
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "payment-processed", generation = 2)
data class MigrationsRenamePaymentProcessed(val amount: Double)

@EventType(id = "payment-processed", generation = 1)
data class MigrationsRenamePaymentProcessedV1(val oldAmount: Double)

class MigrationsRenamePaymentProcessedMigration :
    EventTypeMigration<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1>(
        MigrationsRenamePaymentProcessed::class,
        MigrationsRenamePaymentProcessedV1::class
    ) {
    override fun upcast(builder: EventTypeMigrationBuilder<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1>) {
        builder.renamedFrom(MigrationsRenamePaymentProcessed::amount, MigrationsRenamePaymentProcessedV1::oldAmount)
    }

    override fun downcast(builder: EventTypeMigrationBuilder<MigrationsRenamePaymentProcessedV1, MigrationsRenamePaymentProcessed>) {
        builder.renamedFrom(MigrationsRenamePaymentProcessedV1::oldAmount, MigrationsRenamePaymentProcessed::amount)
    }
}

Java

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.events.migrations.EventTypeMigration;
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "payment-processed", generation = 2)
record MigrationsRenamePaymentProcessed(double amount) {
}

@EventType(id = "payment-processed", generation = 1)
record MigrationsRenamePaymentProcessedV1(double oldAmount) {
}

class MigrationsRenamePaymentProcessedMigration
        extends EventTypeMigration<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1> {
    MigrationsRenamePaymentProcessedMigration() {
        super(MigrationsRenamePaymentProcessed.class, MigrationsRenamePaymentProcessedV1.class);
    }

    @Override
    public void upcast(
            EventTypeMigrationBuilder<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1> builder) {
        builder.renamedFrom("amount", "oldAmount");
    }

    @Override
    public void downcast(
            EventTypeMigrationBuilder<MigrationsRenamePaymentProcessedV1, MigrationsRenamePaymentProcessed> builder) {
        builder.renamedFrom("oldAmount", "amount");
    }
}

Elixir

defmodule MyApp.Events.MigrationsRenamePaymentProcessedV1 do
  use Chronicle.Events.EventType, id: "payment-processed", generation: 1

  defstruct [:old_amount]
end

defmodule MyApp.Events.MigrationsRenamePaymentProcessed do
  use Chronicle.Events.EventType, id: "payment-processed", generation: 2

  defstruct [:amount]
end

defmodule MyApp.Migrations.MigrationsRenamePaymentProcessedMigration do
  use Chronicle.Events.Migration,
    from: {MyApp.Events.MigrationsRenamePaymentProcessedV1, generation: 1},
    to: {MyApp.Events.MigrationsRenamePaymentProcessed, generation: 2}

  alias Chronicle.Events.MigrationBuilder

  @impl true
  def upcast(builder) do
    builder
    |> MigrationBuilder.rename_property(:old_amount, :amount)
  end

  @impl true
  def downcast(builder) do
    builder
    |> MigrationBuilder.rename_property(:amount, :old_amount)
  end
end

TypeScript

import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
class MigrationsRenamePaymentProcessedV1 {
    constructor(readonly oldAmount: number) {}
}

@eventType('payment-processed', 2)
class MigrationsRenamePaymentProcessed {
    constructor(readonly amount: number) {}
}

@eventTypeMigration(MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1)
class MigrationsRenamePaymentProcessedMigration implements IEventTypeMigration<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1> {
    upcast(builder: IEventMigrationBuilder<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1>): void {
        builder.properties(pb => pb
            .renamedFrom('amount', 'oldAmount'));
    }

    downcast(builder: IEventMigrationBuilder<MigrationsRenamePaymentProcessedV1, MigrationsRenamePaymentProcessed>): void {
        builder.properties(pb => pb
            .renamedFrom('oldAmount', 'amount'));
    }
}

Default Value

Sets a default value for a new property:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Migrations;

[EventType("order-shipped", generation: 2)]
public record MigrationsDefaultValueOrderShipped(string TrackingNumber, int RetryCount, string Description);

[EventTypeGenerationFor<MigrationsDefaultValueOrderShipped>(1)]
public record MigrationsDefaultValueOrderShippedV1(string TrackingNumber);

public class MigrationsDefaultValueOrderShippedMigration : EventTypeMigration<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1>
{
    public override void Upcast(IEventMigrationBuilder<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1> builder) =>
        builder.Properties(pb => pb
            .DefaultValue(m => m.RetryCount, 42)
            .DefaultValue(m => m.Description, "default string"));

    public override void Downcast(IEventMigrationBuilder<MigrationsDefaultValueOrderShippedV1, MigrationsDefaultValueOrderShipped> builder)
    {
        // RetryCount and Description did not exist in generation 1 — nothing to map back
    }
}

Kotlin

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.events.migrations.EventTypeMigration
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "order-shipped", generation = 2)
data class MigrationsDefaultValueOrderShipped(val trackingNumber: String, val retryCount: Int, val description: String)

@EventType(id = "order-shipped", generation = 1)
data class MigrationsDefaultValueOrderShippedV1(val trackingNumber: String)

class MigrationsDefaultValueOrderShippedMigration :
    EventTypeMigration<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1>(
        MigrationsDefaultValueOrderShipped::class,
        MigrationsDefaultValueOrderShippedV1::class
    ) {
    override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1>) {
        builder
            .defaultValue(MigrationsDefaultValueOrderShipped::retryCount, 42)
            .defaultValue(MigrationsDefaultValueOrderShipped::description, "default string")
    }

    override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDefaultValueOrderShippedV1, MigrationsDefaultValueOrderShipped>) {
        // retryCount and description did not exist in generation 1 — nothing to map back
    }
}

Java

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.events.migrations.EventTypeMigration;
import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "order-shipped", generation = 2)
record MigrationsDefaultValueOrderShipped(String trackingNumber, int retryCount, String description) {
}

@EventType(id = "order-shipped", generation = 1)
record MigrationsDefaultValueOrderShippedV1(String trackingNumber) {
}

class MigrationsDefaultValueOrderShippedMigration
        extends EventTypeMigration<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1> {
    MigrationsDefaultValueOrderShippedMigration() {
        super(MigrationsDefaultValueOrderShipped.class, MigrationsDefaultValueOrderShippedV1.class);
    }

    @Override
    public void upcast(
            EventTypeMigrationBuilder<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1> builder) {
        builder
            .defaultValue("retryCount", 42)
            .defaultValue("description", "default string");
    }

    @Override
    public void downcast(
            EventTypeMigrationBuilder<MigrationsDefaultValueOrderShippedV1, MigrationsDefaultValueOrderShipped> builder) {
        // retryCount and description did not exist in generation 1 — nothing to map back
    }
}

Elixir

defmodule MyApp.Events.MigrationsDefaultValueOrderShippedV1 do
  use Chronicle.Events.EventType, id: "order-shipped", generation: 1

  defstruct [:tracking_number]
end

defmodule MyApp.Events.MigrationsDefaultValueOrderShipped do
  use Chronicle.Events.EventType, id: "order-shipped", generation: 2

  defstruct [:tracking_number, :retry_count, :description]
end

defmodule MyApp.Migrations.MigrationsDefaultValueOrderShippedMigration do
  use Chronicle.Events.Migration,
    from: {MyApp.Events.MigrationsDefaultValueOrderShippedV1, generation: 1},
    to: {MyApp.Events.MigrationsDefaultValueOrderShipped, generation: 2}

  alias Chronicle.Events.MigrationBuilder

  @impl true
  def upcast(builder) do
    builder
    |> MigrationBuilder.default_value(:retry_count, 42)
    |> MigrationBuilder.default_value(:description, "default string")
  end

  @impl true
  def downcast(builder) do
    # retry_count and description did not exist in generation 1 — nothing to map back
    builder
  end
end

TypeScript

import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
class MigrationsDefaultValueOrderShippedV1 {
    constructor(readonly trackingNumber: string) {}
}

@eventType('order-shipped', 2)
class MigrationsDefaultValueOrderShipped {
    constructor(
        readonly trackingNumber: string,
        readonly retryCount: number,
        readonly description: string
    ) {}
}

@eventTypeMigration(MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1)
class MigrationsDefaultValueOrderShippedMigration implements IEventTypeMigration<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1> {
    upcast(builder: IEventMigrationBuilder<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1>): void {
        builder.properties(pb => pb
            .defaultValue('retryCount', 42)
            .defaultValue('description', 'default string'));
    }

    downcast(_builder: IEventMigrationBuilder<MigrationsDefaultValueOrderShippedV1, MigrationsDefaultValueOrderShipped>): void {
        // retryCount and description did not exist in generation 1 — nothing to map back
    }
}

Value map

The operations above move values between properties. A value map changes the values themselves — it states which value in one generation is which value in the other. This is what you reach for when an enum is renumbered, or a status code takes on a new set of values, and the old numbers now mean something the new generation spells differently.

Override MapValues on the migration rather than declaring it inside Upcast or Downcast:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Migrations;

public enum MigrationsSubscriptionStateV1
{
    Unknown = 0,
    Active = 1,
    Cancelled = 2
}

public enum MigrationsSubscriptionState
{
    Unspecified = 100,
    Running = 101,
    Stopped = 102
}

[EventType("subscription-state-changed", generation: 2)]
public record MigrationsSubscriptionStateChanged(MigrationsSubscriptionState State);

[EventTypeGenerationFor<MigrationsSubscriptionStateChanged>(1)]
public record MigrationsSubscriptionStateChangedV1(MigrationsSubscriptionStateV1 State);

public class MigrationsSubscriptionStateChangedMigration : EventTypeMigration<MigrationsSubscriptionStateChanged, MigrationsSubscriptionStateChangedV1>
{
    public override void Upcast(IEventMigrationBuilder<MigrationsSubscriptionStateChanged, MigrationsSubscriptionStateChangedV1> builder)
    {
        // The value map covers State in both directions
    }

    public override void Downcast(IEventMigrationBuilder<MigrationsSubscriptionStateChangedV1, MigrationsSubscriptionStateChanged> builder)
    {
        // The value map covers State in both directions
    }

    public override void MapValues(IEventValueMapBuilder<MigrationsSubscriptionStateChanged, MigrationsSubscriptionStateChangedV1> builder) =>
        builder.For(current => current.State, previous => previous.State, map => map
            .Map(MigrationsSubscriptionStateV1.Unknown, MigrationsSubscriptionState.Unspecified)
            .Map(MigrationsSubscriptionStateV1.Active, MigrationsSubscriptionState.Running)
            .Map(MigrationsSubscriptionStateV1.Cancelled, MigrationsSubscriptionState.Stopped));
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

Elixir does not support this workflow yet.

TypeScript

TypeScript does not support this workflow yet.

A map declared this way is applied in both directions: forward when upcasting, inverted when downcasting. The pair of values is one fact about the two generations, so you state it once and the two directions cannot drift apart.

Three things are worth knowing:

• Values the map does not mention are carried across unchanged. A map says what changed meaning; it is not an exhaustive listing of an enum that is free to grow.
• Two values collapsing onto one have no single inverse, so the first pair declared for a target value is the one that represents it going back.
• The map does not have to stay on the same property. The two property expressions may name different properties, in which case the map also carries the value across — covering a rename and a re-valuing in one statement.

MapValues is applied before Upcast and Downcast run, so a direction that states its own transformation for the same property keeps it.

How Migrations Work

When an event is appended to the event store:

1. Chronicle identifies the event’s current generation
2. The migration system retrieves all registered migrations for the event type
3. Upcasting: If there are higher generations, the event is transformed upward (1→2→3)
4. Downcasting: If there are lower generations, the event is transformed downward (3→2→1)
5. All generations are stored in the event sequence

This ensures that:

• Older consumers can still read events in their expected format
• Newer consumers can read events with the latest schema
• No data is lost during schema evolution

Registration

Migrations are automatically discovered and registered when you connect to Chronicle. Simply implement IEventTypeMigrationFor<TEvent> in your client application, and Chronicle will:

1. Discover all migrators via IClientArtifactsProvider
2. Build migration definitions with JmesPath transformations
3. Send the definitions to the kernel during event type registration

Catching Misuse Early

Two runtime checks and two code analysis rules exist specifically to stop a broken migration before it ever reaches a real event log:

• MigrationGenerationsMustShareEventTypeId — thrown from EventTypeMigration<TUpgrade, TPrevious>’s constructor the moment TUpgrade and TPrevious resolve to different event type ids. This turns the old style’s classic mistake — an omitted or mismatched id on the previous generation — into a loud failure at application startup instead of a confusing, silent rejection at the kernel.
• MultipleMigratorsForSameEventTypeGeneration — thrown by EventTypeMigrators.GetMigratorsFor when two different migrator classes both claim to bridge the same generation pair for one event type. Exactly one migrator may own a generation transition.
• CHR0037 flags a migration whose two generations don’t resolve to the same event type at compile time — including validating, for the new attribute, that [EventTypeGenerationFor<T>]’s T really is the migration’s TUpgrade.
• CHR0049 flags [EventTypeGenerationFor<T>] when T isn’t itself marked with [EventType] — the referenced type must carry the real identity directly, not another generation marker.

Best Practices

1. Mark previous generations with [EventTypeGenerationFor<T>]: it resolves the event type id from the current generation’s own [EventType], so the two can never drift apart the way a hand-typed id on both generations can
2. Incremental generations: Always migrate between consecutive generations (1→2, 2→3, not 1→3)
3. Reversible transformations: Ensure downcast can recreate the original structure where possible
4. Default values: Use DefaultValue() for new properties that didn’t exist in older generations
5. Test migrations: Verify both upcast and downcast transformations work correctly
6. Document changes: Keep track of what changed between generations in your event types