Event versioning (or why I sometimes modify the event store)

Requirements and applications evolve and change, leading to refactoring. For example, user registration now requires a first and last name, what was once an error may no longer be considered one, etc. In an event sourced application, that poses a few problems. In this post I’ll discuss a few strategies and my views on event versioning.

On immutability and legacy events

Consider legacy events that, based on new requirements, are:

• No longer relevant;
• Misnamed;
• Missing information;
• Too coarse-grained (high level) or too fine-grained (low level).

Some people argue that event stores in general, and events in particular, are immutable. That modifications to existing events should not happen, and any corrections must be made by new events. After all, events are a record of history, and history does not change.

This has some implications when it comes to the mutations listed above. Regardless of new versions of events, to prevent errors and inconsistent state, old events and their handlers need to be maintained indefinitely. Potentially, this also holds for event listeners that depend on the old events.

Needless to say, depending on the rate of change of the application and its events, this can dramatically increase technical debt and complexity.

Archiving events

Consider a domain where aggregates have a limited “lifespan”. For example, a site with classifieds that are automatically removed after a certain period of time. Once these aggregates have become inactive (i.e., after applying a Deleted event), they will not process new commands or apply events.

Following that train of thought, all existing events for those aggregates can be safely moved to a secondary (archival) event store. This satisfies immutability (nothing is removed or modified), but it also ensures that the events do not take up memory, index space, etc., reducing the working set.

An alternative approach would be to move those events to inexpensive, slow (but replicated) storage. That way, the events will remain available, but with significantly increased latency.

Event upcasting

Upcasting satisfies the requirement for an immutable event store. An upcaster is called when reading (old) events from a stream or store, before these events are pushed to event listeners, projections, etc. The original events are not touched, but the upcaster can map our new understanding of the world on those events.

In general, I consider an upcaster to be some method f that takes an event of a revision x, and turns it into zero or more events of revision x + 1. In other words, Event_V2 = f(Event_V1). It’s not something that can be fully automated, instead we will have to write a little code.

Let’s assume that, during user registration, an event was applied containing the date and time of registration. After some iterations, it’s decided that the time component is no longer of interest, just the date component:

case class UserRegistered_V1(userId: String, name: String, timestamp: java.time.LocalDateTime)

case class UserRegistered_V2(userId: String, name: String, date: java.time.LocalDate)

def upcast(event: Any): Seq[Any] = event match {
  case u: UserRegistered_V1 => Seq(UserRegistered_V2(u.userId, u.name, u.timestamp.toLocalDate))
  case _ => Seq(event)
}

In this case, an event listener interested in UserRegistered events will only have to handle the last version of an event (UserRegistered_V2). They will never see UserRegistered_V1. This reduces the amount of code that has to be supported.

Of course, upcasters do have a performance impact, depending on the number and type and complexity of the work they do. For example, to construct a new version of an event, an upcaster might need to pull in data from other events or data sources.

Additionally, be aware that existing projections or subscribers are not automatically updated (only during replays).

Framework support

Here’s an overview of how upcasting can be implemented in some of the popular event sourcing frameworks:

• Axon Framework: has native support for Event Upcasters, which can also (de-)multiplex events (changing the granularity, i.e. splitting or merging). No longer relevant events can be converted to the empty list.
• Akka Persistence: by writing a custom Event Adapter, upcasting can be implemented in the fromJournal method; (de-)multiplexing is possible.
• Broadway: no (native) support for upcasting, there is however a pull request to add that to the library.
• Prooph: upcasting can be achieved by using the UpcastingPlugin. (De-)multiplexing is supported. (Updated Nov 2017)
• Event Store (not really an event sourcing framework, but rather a journal): other than copying all events from a stream to a new stream, updating each event as it is copied, there seems to be no built-in support for event versioning or upcasting. Potentially, you could do some transformation when reading events (in a query). It seems that code would have to be repeated for every query that deals with those events.

Let me know if there are frameworks missing from this list!

Rewriting events

This is where it might become a little controversial 😉

I’m a practical person. My personal view is that there are cases where directly modifying or deleting events is a perfectly valid and acceptable scenario. Such modifications can be done by directly accessing the database (for trivial cases), or programmatically:

1. Load the events that need to be refactored.
2. De-serialize event payload.
3. Modify event payload.
4. Serialize event payload.
5. Write modified event back to event store.

As with all powerful tools, there are some inherent issues and dangers:

• Running code that depends on the old structure of the events that are modified. This can be mitigated by performing the refactoring on application startup (but that means downtime), or saving the events as a new collection (and then switching to that collection at some point).
• Removing or renaming the wrong events.
• Breaking serialization.
• Like with upcasting, existing projections or read models are not automatically updated.

So use with caution, but do consider it a part of your toolkit.

I’m keen to hear your thoughts!