Skip to content

Event sourcing and ledgers

Storing each change as an immutable, appended record and deriving current state from the history. A strong design answer covers how you rebuild state, keep reads fast, and correct a mistake without editing the past.

On this page

What it is

Event sourcing stores every change to an entity as an event in an append-only store, and that store is the system of record. Each entity has its own ordered stream, and the application derives the entity's current state by replaying the stream from the start; the pattern guide in the Azure Architecture Center calls this rehydration. Events describe what happened in the domain, such as AddedItemToOrder or OrderCanceled, with the data needed to describe that action. Martin Fowler's description frames the same idea as capturing all changes to application state as a sequence of events, with the consequence that you can throw the state away and rebuild it from the log.

A ledger applies the same append-only idea to money, with or without the full event-sourcing machinery. Each movement of funds is recorded as an entry that is appended and then not changed; a balance is the sum of the entries on an account, or a stored total kept in step with them. Double-entry adds a rule: a transaction needs a debit side and a credit side, at least two entries in all, and the two sides sum to the same amount. Modern Treasury describes enforcing this at the application layer when a transaction is created, grouping entries by currency so that each currency balances on its own. Square's Books service follows the same model, with books such as Payments, Refunds, Pending Balance and Payouts that pennies move between, each journal entry summing to zero.

PieceWhat it doesWhy it exists

Event stream

Ordered events for one entity

The history and the source of truth

Rehydration

Replay the stream to compute state

Lets a command check rules against current state

Expected version

Append is rejected if the stream changed since the read

Stops two handlers acting on the same stale state

Projection (read model)

A derived view kept up to date by a handler from new events

Reads don't replay; they query a view shaped for the query

Snapshot

Saved state at a point in the stream

Replay just the events after the snapshot; rebuildable from the stream

Compensating event

A new event that reverses or corrects an earlier one

The original stays; history shows the correction

How a write works. A command handler loads the entity's stream, replays it to get the current state, runs the business rule and appends new events. Two handlers that load the same stream at once would see the same state (both see five seats left, both accept), so event stores use optimistic concurrency: an append that names the version the handler read is rejected if the stream has grown since. The loser reloads, re-evaluates and retries. Appending also avoids the row-level locking of an update-in-place table, which is where the write-throughput gain comes from.

How a read works. Replaying a stream on each query is costly, so a handler listens for new events and updates a materialized view, a projection shaped for the query (all orders for a customer, say). A projection lags the store by the time it takes to publish and handle the event, so reads from it are eventually consistent. Delivery to those handlers is usually at least once, so a handler must be idempotent, for example by tracking the last event sequence number it applied and skipping repeats. For long streams, a snapshot taken after each N events means rehydration loads the latest snapshot and replays just the events after it; the stream stays the source of truth and the snapshot can be regenerated from it.

Ledgers in practice. A ledger API can expose mutable-looking things, such as an account balance or a transaction that moves from pending to posted, while keeping an immutable append-only log underneath, so any past state is recoverable by filtering on an effective timestamp or a version number. Square's post describes the other usual compromise: a books table that holds a running balance, updated on each transaction, while the journal and entry tables take inserts only. Before that design, paying out a merchant meant an expensive group-by over all of their payments to compute the balance, which struggles once payouts reach millions a day.

Fixing the past. Because the store is the permanent record, you don't update or delete an event; you append a compensating event, such as ReservationCanceled after SeatsReserved. The same rule applies to money: a journal entry written by a buggy deploy is corrected by a new entry, and the balance moves while the trace of the mistake stays. Reversal is easiest when an event is stored as a difference (add $10) rather than a resulting value (set to $110), because a difference can be undone without knowing the prior state. When a bug was in the code rather than the data, you fix the code and replay, as long as side effects to external systems are gated so a replay doesn't resend them.

When to use it

Reach for an event store when the history is itself a requirement: you need an audit trail, you need to answer what the state was at a time in the past, or you want the intent behind a change (two seats reserved) rather than just the result (42 seats left). It also fits when updates to the same entity contend, because appends don't take the row locks that read-modify-write cycles do, and when you expect to build new read models later from the same events without touching the write path.

Use a double-entry ledger when your system moves funds between parties: wallets, payouts, refunds, credits. The per-currency balance rule catches a transaction that creates or destroys value, which a plain balance = balance - 100 update doesn't. Our advice in a round: say which accounts the money moves between for one transaction (customer cash, pending payouts, fees) and how the balance is read, from a stored running total or from a sum over entries.

Apply it to one part of the system, not all of it. The payment ledger or the order pipeline can be event-sourced while user profiles and configuration stay as plain rows. Each entity's stream is independent, so an event store partitions by entity ID, which keeps sharding simple when the time comes.

When not to

Plain create, read, update and delete is the right choice when the requirement is just current-state reads and writes: a product catalog, lookup tables, settings, a prototype with a short expected life. The event store, the schema-evolution plan and the projection infrastructure are up-front costs that these systems don't repay. The same goes for a feature that must read its own write immediately from a view, because the gap between appending an event and updating a projection is built into the pattern.

If all you want is an audit trail, ordinary logging or an audit table next to a mutable row may be enough. If your team hasn't run an event-driven system before, the changes to testing, debugging and operations raise the risk of mistakes that are expensive to reverse. And an append-only store collides with laws that require personal data to be deleted, so either keep personal data outside the events and reference it by ID, or encrypt it per subject and delete the key (crypto-shredding).

A message broker is not an event store. Kafka and similar logs work well to fan events out to projections and other services, but they typically lack per-entity stream reads and optimistic concurrency on append, so they don't replace the store the command handler reads from. See Queues and logs for what a log does well.

Compared

ApproachWhat is storedCurrent state comes fromWhen it is the right one

Mutable rows (CRUD)

The latest value, overwritten in place

The row itself

Current-state reads and writes, static or reference data, short-lived systems

Mutable rows plus an audit table

Latest value, plus a separate record of each operation

The row; the audit table is for review

You need a trail for support or compliance but no replay or rebuild

Event store

Immutable events per entity, in order

Replay (with snapshots), served through projections

Intent matters, updates contend, or you'll want new read models from the same history

Double-entry ledger

Immutable entries grouped into balanced transactions

A running balance per account, or a sum over entries

Anything that moves funds and must show where each unit came from and went

Broker log (Kafka)

A stream of events for consumers to read, without per-entity stream queries

Consumers build their own state

Distributing events to many consumers; not a per-entity store with version checks

In a picture

replayallowedversionedCommand handlerEvent streamCurrent stateAppend event

Step 1 of 3

Append, don't overwrite

A command handler loads the entity's stream and replays it to get the current state. If the business rule passes, it appends a new event, naming the stream version it read. The store rejects the append if another writer got there first, and the handler reloads and retries.

How to say it in an interview

The common mistake

Quiz

Two command handlers load the same seat-reservation stream, both see five seats left, and both try to reserve four. What prevents a double booking?
A deploy last week wrote wrong events into several streams. What's the right fix?
A transaction debits a user's USD account $4,586.51 and credits their ETH account 1 ETH, with no other entries. Does it pass a double-entry check?
An account stream has grown to millions of events and loading it before each command is slow. What's the standard fix?

Questions that use this

Related

Sources

  1. Azure Architecture Center: Event Sourcing pattern
  2. Martin Fowler: Event Sourcing
  3. Modern Treasury: How to Scale a Ledger, Part V: Immutability and Double-Entry
  4. Square Corner Blog: Books, an immutable double-entry accounting database service
Sign in to report a mistake