{"canonical_url":"https://engineer.company/glossary/event-sourcing/","content_markdown":"# Event sourcing\n\n## What it is\n\nEvent sourcing is a way of storing data in which the record of what happened is\nthe data. Most applications keep the current state of an order or an account in\na row and overwrite it on every change. An event-sourced application keeps the\nchanges instead: each one is appended to a log as an event, and the current\nstate is worked out from that log whenever it is needed. Martin Fowler, who\ndescribed the pattern in 2005, put it in one line: \"Capture all changes to an\napplication state as a sequence of events.\"\n\nAn event records something that has already happened. Greg Young's CQRS\nDocuments ask for every event to be named as a verb in the past tense, such as\n`CustomerRelocated` or `CargoShipped`, because the name is part of the language\nthe business uses about its own work. A fact about the past cannot be undone, so\nevents are never edited or removed. Young compares the log to an accountant's\nledger, where a wrong entry is not rubbed out but corrected by a new one, and he\napplies the same rule to deletion. When a customer takes two pairs of socks back\nout of a cart, the log gains a \"removed\" event. Young calls such an entry a\nreversal: the cart ends up as if the socks had never been added, and the log\nstill shows that they were.\n\nThe events are kept in streams, one per thing whose state they describe. Young,\nwho builds on domain-driven design, calls that thing an aggregate. Each event\ncarries the stream's id and a version number that is unique and sequential\nwithin that stream, so the order of events is never in doubt. To load an order,\nthe application reads the order's events by version and applies each one in\nturn. Young points out how little the store itself has to do: at its simplest it\noffers two operations, reading every event of one stream in order and appending\nnew events to it.\n\nThat makes the log the system of record. Fowler notes that either the log or the\ncurrent state can be the official record. In an event-sourced system it is the\nlog, and everything else, a table of current balances, a search index, a report,\nis a copy derived from it that can be thrown away and built again.\n\n## Why it matters\n\nFowler names three things a complete log makes possible. A complete rebuild: the\napplication state can be discarded and recreated by replaying every event onto\nan empty application. A temporal query: the state at any past moment is the\nresult of replaying the events up to that moment. And event replay: when an\nevent turns out to have been wrong, the system can reverse it and the events\nafter it, then replay the corrected sequence. The same log is also an audit\ntrail that nobody had to remember to write, and Fowler mentions support and\ndebugging as everyday uses: a support team can see exactly what a user did, and\na developer can replay production events in a test environment.\n\nYoung shows the payoff with two teams at an online retailer, both asked for a\nreport on items that customers remove from their carts. The team that stores\nonly current state starts recording removals now, and its report has data from\nthat day on. The team that stores events writes the same report handler and runs\nit over the log from the beginning, so its first report reaches back years. A\nquestion nobody thought to ask when the system was built can still be answered,\nbecause the system kept what happened rather than what it ended up as.\n\nEvents are also how other systems learn about a change. Young observes that many\nsystems save their state and then publish an event to a queue, which strictly\nneeds a two-phase commit between the two, since a crash in between leaves them\ndisagreeing. His alternative is to treat the event store itself as the queue: a\nsequence number on every event lets a separate process publish the events in\norder, so there is only one write. And because the store is append-only, it is\neasier to scale. Young notes that append-only storage needs far fewer locks than\nstorage that updates in place, and that the aggregate id is the only key an\nevent store ever has to be partitioned by.\n\nThe costs are real, and Fowler states them. Packaging every change as an event\nis a style of programming that not everyone is comfortable with, and the pattern\nis very hard to add later to a system that was not built around it. The store\nalso answers only one kind of question, \"give me this stream\". Young's example\nis that an event store cannot tell you which users are named Greg; questions\nlike that need a separate read model, built from the events, which is why he\ntreats event sourcing and CQRS, separating the models for writing and reading,\nas a pair.\n\n## What it looks like in practice\n\nThe smallest working event store is one PostgreSQL table, close to the layout\nYoung gives (an aggregate id, the event's data and a version). Here it holds the\nstock of one item on sale. Each event carries a change to the number of units on\nsale rather than the new total, the form Fowler calls the most straightforward\nto reverse: \"add ten\" is undone by subtracting ten, while \"set to 110\" has lost\nthe value it replaced.\n\n```sql\nCREATE TABLE stock_events (\n    item_id  text    NOT NULL,\n    version  integer NOT NULL,\n    event    text    NOT NULL,\n    order_id text,\n    units    integer NOT NULL,  -- change to the units on sale\n    PRIMARY KEY (item_id, version)\n);\n\nINSERT INTO stock_events VALUES\n    ('item-881', 1, 'ItemStocked',   NULL,   100),\n    ('item-881', 2, 'UnitsHeld',     'A-17',  -2),\n    ('item-881', 3, 'HoldExpired',   'A-17',   2),\n    ('item-881', 4, 'UnitsHeld',     'B-02',  -1),\n    ('item-881', 5, 'HoldConfirmed', 'B-02',   0);\n\n-- current state: fold the whole stream\nSELECT sum(units) AS on_sale FROM stock_events\nWHERE item_id = 'item-881';                    -- 99\n\n-- temporal query: the item as it stood after version 2\nSELECT sum(units) AS on_sale FROM stock_events\nWHERE item_id = 'item-881' AND version \u003c= 2;   -- 98\n```\n\nThe primary key does the work Young assigns to an optimistic concurrency check.\nTwo checkouts that both read the stream at version 5 and both decide to hold a\nunit will each try to append version 6:\n\n```sql\nINSERT INTO stock_events VALUES ('item-881', 6, 'UnitsHeld', 'C-40', -1);\nINSERT INTO stock_events VALUES ('item-881', 6, 'UnitsHeld', 'D-11', -1);\n-- the second fails: (item-881, 6) already exists\n```\n\nPostgreSQL's documentation describes a primary key over a group of columns as\nmaking that combination unique, and an insert that would duplicate it raises an\nerror. The checkout that lost reloads the stream, checks that a unit is still on\nsale, and tries again as version 7. Neither of them ever sold a unit that was\nnot there, and the log shows both decisions in the order they were made.\n\nThe note\n[Selling the last ticket exactly once](/notes/selling-limited-stock-without-overselling/)\nworks through the same stock problem and shows where this shape gets tight. Its\nfirst answer keeps the count in one row and changes it with a single conditional\n`UPDATE`, and it advises against optimistic locking on a hot counter, because a\nversion column turns contention into retries. For the hottest item it puts every\nrequest on one Kafka partition, read by a single consumer that keeps the count\nin memory and commits its decisions in batches, and calls this the LMAX shape.\nFowler's article on the LMAX architecture, one of the note's sources, describes\nevent sourcing at its purest: a trading engine with no database at all, whose\nwhole state can be derived from its input events, which a journaler stores\ndurably so they can be replayed. The note's checkout uses events of a different\nkind. Each step writes a message to an outbox table, change data capture\npublishes it, and the tables remain the record. Those events announce changes;\nin event sourcing, the events are the record.\n\n## Where it goes wrong\n\n**Replaying the log repeats its side effects.** A handler that sends a\nconfirmation email or charges a card does it again when the log is replayed, and\nFowler points out that external systems cannot tell a replay from real work.\nRebuilding a read model can then send every customer last year's emails. Put\nevery external system behind a gateway that knows when the application is\nreplaying and drops outgoing calls during a replay, so the domain logic never\nhas to know. Queries need the same care: Fowler's example is a currency\nconversion, where a replayed event needs the exchange rate of its own day, not\ntoday's, so the gateway should record the answers it received and return them on\nreplay.\n\n**A busy stream turns into retries.** Optimistic concurrency assumes conflicts\nare rare. When many writers append to one stream at once, every conflict means\nreloading the stream and trying again, and under a burst of traffic the retries\nbecome the load, which is the warning the note above gives about version\ncolumns. Draw streams so that one rarely has two writers at the same moment: one\nstream per order rather than one for a whole product line. Where a single stream\nreally is hot, give it a single writer, as in the LMAX design, so that there is\nnothing left to conflict.\n\n**Long streams load slowly.** Replaying thousands of events to load one object\ncosts time on every request, and Fowler lists slow rebuilds among the reasons to\nkeep a current-state copy. Young's answer is the rolling snapshot: the\nserialised state of a stream at a known version, kept in a table of its own and\nwritten in the background by a separate process, so that loading means the\nnewest snapshot plus the events after its version. Keep snapshots out of the\nevent log itself: Young describes a snapshotter on a busy stream failing its\nconcurrency check again and again. He also recommends building without\nsnapshots, since they can always be added later to make loading faster.\n\n**Readers fall behind the writer.** Every read model is built from the events\nafter they are written, so it trails the log. Fowler warns that systems reading\nthe log are liable to be out of step with it, and a user who submits a form and\nthen sees a list without the change will submit it again. Have each read model\nrecord the last event it applied, so its lag can be measured and it can be\nrebuilt from the start, and show users the outcome of their own command from the\ncommand's response rather than from a read model that may not have caught up.\n\n## Further reading\n\n- [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html)\n  — Martin Fowler's description of the pattern: complete rebuild, temporal\n  query, event replay, and gateways that keep replays from reaching other\n  systems.\n- [CQRS Documents by Greg Young](https://cqrs.wordpress.com/wp-content/uploads/2010/11/cqrs_documents.pdf)\n  — events as facts in the past tense, reversal instead of delete, a two-table\n  event store, rolling snapshots and the event store as a queue.\n- [The LMAX Architecture](https://martinfowler.com/articles/lmax.html)\n  — an in-memory trading engine whose entire state is derived from journaled\n  input events.\n- [PostgreSQL: Constraints](https://www.postgresql.org/docs/current/ddl-constraints.html)\n  — unique and primary-key constraints over a group of columns, the database's\n  side of an optimistic concurrency check.\n\n\u003chttps://engineer.company/glossary/event-sourcing/\u003e\n","date_modified":"2026-10-29T11:17:41Z","description":"How event sourcing stores every change as an event and derives state from the log, what that buys a team, and four ways it goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/event-sourcing/index.gmi","gopher":"https://engineer.company/glossary/event-sourcing/gophermap","html":"https://engineer.company/glossary/event-sourcing/","json":"https://engineer.company/glossary/event-sourcing/index.json","markdown":"https://engineer.company/glossary/event-sourcing/index.md","pdf":"https://engineer.company/glossary/event-sourcing/index.pdf"},"kind":"page","language":"en","title":"What is event sourcing?","url":"https://engineer.company/glossary/event-sourcing/","version":1}