Event Sourcing Example & Explained in plain English

What is Event Sourcing? It’s a way of storing data that is probably very different than what you’re used to. I’ll explain the differences and show ab event sourcing example that should clear up all the mystery around it.

YouTube

Check out my YouTube channel where I post all kinds of content that accompanies my posts including this video showing everything that is in this post.

Source Code

Developer-level members of my CodeOpinion YouTube channel get access to the full source in this post available in a git repo. Check out the membership for more info.

Current State

The vast majority of apps persist current state in a database. Regardless if you’re using a relational database (RDBMS) or a document store (NoSQL), you’re likely used to storing current state.

To illustrate this, here’s a table that represents products.

Event Sourcing

If we were to have some behavior in our system that is to receive product into the warehouse, we would increment the quantity value. So for example, if we received more quantity for SKU ABC123, we would update quantity value. If we shipped product out of the warehouse, we would decrease the quantity value.

One question to ask from the table above, how did we get to the current state of Quantity of 59 for product ABC123?

Because we only record current state, we have no way to know with absolutely certainty how we got to that number.

Yes, if added logging you could infer with some degree of certainty how you got to a particular state. However, it would not be guaranteed because it actually requires you to write logs in every place that you’re changing state, include outside of your application. This could be incredibly difficult. Ultimately your current state is the point of truth, no matter how you got to that state.

Event Sourcing

Event Sourcing is a different approach to storing data. Instead of storing the current state, you’re instead going to be storing events. Events represent the state transitions of things that have occurred in your system.

They are facts.

To illustrate the exact same product of SKU ABC123 that had a current state quantity of 59, this is how we would be storing this data using event sourcing.

It’s important to note that events are persisted in what is called an event stream. Event streams are generally per unique aggregate. So in my example, a single product SKU. The above is the stream of events for SKU ABC123.

With the above events, we can see that we Received a quantity of 10. Then we Received 5 more. Followed up by having Shipped out 6. Finally there some extra quantity that was magically found in the warehouse so it was adjusted by another 50. This got us to our current state of 59.

Event Sourcing Implementation

First is to define the events that occur that we want to record. Events are facts that something has occurred. They are generally the result of a state changes from commands. Here’ are the 3 events I’ve defined in our the event stream.

Next comes our aggregate. It is responsible for creating events that will get persisted to the event stream. The aggregate exposes methods to perform commands/actions to our domain. If our business logic passes, then we’ve confirmed that an event has occured.

When an event is added, we call the appropriate Apply() method. These methods are to keep track of the current state within our aggregate so we can perform the relevant business logic (which throws an InvalidDomainException).

Repository

For demo purposes, I’m not using an actual database to store our event stream, but rather just in-memory dictionary and list to illustrate. The important part is your repository is responsible two things, building your aggregate and saving the events from your aggregate.

When you want to build/get a WarehouseProduct from the Repository, it will get the events from the event stream, then call ApplyEvent() for each existing event. This is replaying all the events in the aggregate to get back to current state.

Then after you have called commands like ShipProduct/ReceiveProduct/AdjustInventory, the new events will get appended to the event stream from the Repositories Save() method.

Projections

The current state used in the aggregate is called a projection. It represents the current state of the event stream. I’ve covered more about projections and how they are used in UI and reporting to build many different models from your event stream.

Demo App

I’ve created a simple console application that has all the code above in an interactive way. Developer-level members of my CodeOpinion YouTube channel get access to the full source and demo available in a git repo. Check out the membership for more info.

Follow @CodeOpinion on Twitter

Enjoy this post? Subscribe!

Subscribe to our weekly Newsletter and stay tuned.

Event Sourcing: Projections with Liquid Projections

Liquid Projections

Projections are an important yet pretty simple concept when working with event-centric or event sourcing systems. The concept is to build a state from a stream of events. In my previous post, Event Sourcing with SQL Stream Store, I made a pretty basic projection to keep the current account balance. In this post, I’ll use Liquid Projections to accomplish the same task.

I recommend checking out my post on SQL Stream Store as I’m using the same example/demo application in this post.

Liquid Projections

Liquid Projection is a library for building projections. The concept and API are pretty simple, and I’ll cover the basics in this post.

First I’ll update my Demo Application to use the Liquid Projections NuGet package.

Event Map

The first building block is creating an event map. The idea is to map an event to an action that we want to be invoked when the event occurs. We can use the EventMapBuild<TContext> to create all of our event mappings. The TContext can be anything but I’ll be using it to mutate the state that represents the current balance.

As a refresher from my previous post, here is the Balance

Now using the EventMapBuilder<Balance> to handle the Deposited and Withdrawn events.

You’ll notice call Build() on the EventMapBuilder<Balance> which will return us the EventMap<Balance>. At this point, you can call Handle() to pass in the events incoming from our subscription with our current Balance.

Conditions

There are also some nice additions such as providing conditions for when to execute a map. For example, if you wanted to handle only deposited events where the amount was greater than 100.

Inheritance

There is also support for inheritance, which means since my Deposited and Withdrawn events inherit from the AccountEvent base class, I could also have done

Event Store Integration

The next on my list is write this up directly with to something like Event Store or SQL Stream Store. Stay tuned.

Check out Liquid Projections on GitHub for more.

All the source code shown in this post is available on GitHub.

If you’d like a more detailed contented related to various aspects of event sourcing, let me know in the comments or on twitter.

Related Links:

Follow @CodeOpinion on Twitter

Enjoy this post? Subscribe!

Subscribe to our weekly Newsletter and stay tuned.

Event Sourcing with SQL Stream Store

Event Sourcing with SQL Stream Store

I’ve known about SQL Stream Store for a bit (I believe when it was called Cedar) but haven’t really looked into it much. The premise is to provide a stream store over SQL. Currently supporting MS SQL Server, PostgreSQL, and MySQL. Meaning it is simply a .NET Library you can use with an SQL implementation. Let’s take a look at how you can implement Event Sourcing with SQL Stream Store.

SQL Stream Store Demo Application

For this demo/sample, I’m going to create a .NET Core 3 console app. The idea will be to create the stereotypical event-sourcing example of a bank account.

I wanted to explore the primary functions needed of an event stream.

  • Create a Stream
  • Append a new Event to a Stream
  • Read Events from a Stream
  • Subscribe to a Stream to receive appended Events

NuGet Package

As always, the first thing is to get the SqlStreamStore NuGet Package by adding it as a PackageReference in your csproj.

I’ve also included Newtonsoft.Json because I’m going to be (de)serializing events.

Events

I’m going to create two events to represent the bank account transactions. Deposited and Withdrawn. Both of these will extend the abstract AccountEvent that will contain the TransactionId, Dollar Amount, and DateTime of the event.

Creating a Stream

There is no way of creating an empty stream. This is actually really nice. Instead when appending an event to a stream, if the stream does not already exist, it’s created. This is the same how EventStore works and should also feel familiar in comparison to the API.

Appending to a Stream

Appending a new event to a stream is pretty straight forward. From the IStreamStore there is an AppendToStream method that takes a few args.

The first is StreamId. This generally would represent your aggregate root ID. In this demo, I’m setting it Account:{GUID}.

The second arg is ExpectedVersion. This is also similar to the EventStore API. This is used for handling concurrency. You can specify an integer that represents the number of events that are persisted in the stream. You can also use the ExpectedVersion enum that can specify Any to not concern yourself with concurrency or NoStream to verify its the first event.

Finally, the 3rd param is an instance of NewStreamMessage. It contains the MessageId (GUID), an event name and the event json body.

An interesting takeaway here is the event name is intentionally made as a string so you are not serializing/deserializing to the CRL type name. This is a great idea since the CLR type name is likely to be changed more than just a plain string which you can keep constant.

Reading a Stream

You can read a stream forward or backward. Forward meaning from the very first event until the last, which is what I’ll use in this example.

You simply specify the StreamId, the starting version (0) and how many events to pull from the stream. The result contains an IsEnd to indicate there are no more events left in the stream to read.

Subscribing to a Stream

Subscribing to a stream is pretty straight forward. Specify the StreamId, the starting version/position of where you want to be notified of new events from, and then StreamMessageReceived for handling the newly appended event.

Wrapping it up

Now that I’ve covered all the primary aspects, it’s just a matter of adding some input/output to our console app by allowing the user to deposit and withdrawal from the account.

In the demo, I’m using the InMemoryStreamStore so there is no persisted data upon restarting the app. I’m also using a new GUID to represent the AccountId on each run.

Source Code

All the source code shown in this post is available on GitHub.

This was a quick look at just a few of the APIs in SQL Stream Store but should give you a feel for how it works.

If you’d like a more detailed contented related to various aspects of event sourcing, let me know in the comments or on twitter.

https://github.com/dcomartin/SqlStreamStore.Demo

Related Links:

Follow @CodeOpinion on Twitter

Enjoy this post? Subscribe!

Subscribe to our weekly Newsletter and stay tuned.