A B C D E F G H I J K L M N O P Q R S T V W Y Z А Б В Г Е И К Л М О П С Т Ц

Event Sourcing

Event Sourcing

 

Event Sourcing это архитектурный паттерн хранения состояния, при котором система записывает не текущее значение сущности, а неизменяемую последовательность событий, которые к нему привели. Текущее состояние получается сверткой событий по порядку, а журнал только дописывается и становится единственным источником истины. Паттерн описал в декабре 2005 года Martin Fowler (Мартин Фаулер), автор книг о разработке корпоративных приложений, а сегодня он входит в каталог облачных паттернов Microsoft Azure.

Практика ниже воспроизведена на PostgreSQL 18.6 с хранилищем событий без фреймворка. Готовые хранилища событий, специализированная база KurrentDB, библиотека Marten и фреймворк Axon, описаны по официальной документации.

 

Что такое Event Sourcing и какую задачу решает

Обычная CRUD-таблица хранит последнее значение. Заказ лежит строкой со статусом и суммой, и каждый UPDATE затирает предыдущую версию. На вопрос «что было в заказе вчера в 15:00 и почему изменилась сумма» такая таблица не отвечает. Ответ ищут в логах или в отдельной таблице аудита, которая расходится с основной при первой же ошибке.

Event Sourcing переворачивает модель. Факт «в заказ добавлена книга» записывается событием ItemAdded, и это событие больше никогда не меняется. Состояние на любую прошлую версию восстанавливается проигрыванием событий до неё, а аудит получается бесплатно, потому что история и данные здесь одно и то же. Описание паттерна в Azure Architecture Center формулирует суть так же, полная серия действий над объектом хранится в хранилище только на добавление вместо одного текущего состояния.

Event streaming передаёт и обрабатывает поток событий между системами, очередь сообщений доставляет задачу получателю и забывает её. Event Sourcing отвечает на другой вопрос, а именно как хранить состояние сервиса, и от брокера не зависит. В практике ниже журнал это одна таблица PostgreSQL.

 

Архитектура и ключевые понятия

Паттерн держится на событии, потоке, агрегате и хранилище событий, а для чтения к ним добавляются модели чтения.

 

Событие, поток и агрегат

Событие (event) это неизменяемая запись о факте, который уже произошёл в предметной области. Имя ставится в прошедшем времени (OrderCreated, ItemAdded, OrderPaid), внутри лежат полезная нагрузка (payload) и метаданные, например имя команды, породившей событие. Отменить событие можно только новым, компенсирующим, вроде ItemRemoved.

Агрегат (aggregate) это понятие из DDD (Domain-Driven Design, предметно-ориентированное проектирование), граница согласованности, внутри которой действуют бизнес-правила, или инварианты. Заказ с позициями и статусом образует один агрегат. События одного агрегата складываются в поток (stream), упорядоченный номером версии.

 

Хранилище событий и модели чтения

Хранилище событий (event store) это журнал только на добавление (append-only) с двумя операциями. Первая дописывает события в конец потока при условии, что поток находится на ожидаемой версии. Вторая читает один поток либо весь журнал начиная с некоторой глобальной позиции. Изменения и удаления событий в контракте нет.

Сворачивать поток на каждый запрос списка заказов дорого, поэтому чтение обслуживают отдельные модели чтения (read model), которые ещё называют проекциями. Проектор читает журнал, применяет события к денормализованной таблице и запоминает, докуда дочитал. Любую модель чтения можно стереть и пересобрать из журнала с нуля.

 

Принцип работы, от команды до проекции

Запрос на изменение приходит командой (command), например «добавить позицию в заказ». Обработчик команды каждый раз проходит одну и ту же цепочку шагов:

  • Загрузка. Чтение событий потока агрегата целиком или снапшота с хвостом событий после него.
  • Свертка. Применение событий по порядку версий к начальному состоянию, на выходе текущее состояние и его версия.
  • Проверка инвариантов. Команда сверяется с состоянием, и добавить позицию в отгруженный заказ не получится, команда отклоняется до записи.
  • Запись. Новые события дописываются в поток с ожидаемой версией, равной прочитанной, и если поток успел уйти вперёд, запись не проходит.
  • Проекция. Проекторы асинхронно читают журнал по глобальной позиции и обновляют модели чтения.

Таким образом, запись и чтение разведены по разным моделям, а это и есть CQRS (Command Query Responsibility Segregation, разделение ответственности команд и запросов). Azure Architecture Center прямо пишет, что Event Sourcing обычно сочетают с CQRS. Цена разведения в том, что модель чтения отстаёт от журнала, и та же документация называет систему с проекциями согласованной только в конечном счёте (eventual consistency).

Поток данных в Event Sourcing: команда загружает события агрегата, проверяет инварианты и дописывает новые события в журнал, проекторы читают журнал по глобальной позиции и обновляют модели чтения

Когда модели чтения живут в других сервисах, события до них обычно везёт брокер сообщений вроде Apache Kafka. Producer, consumer и архитектуру потоковых приложений на нём разбирает курс Apache Kafka для разработчиков.

Apache Kafka для инженеров данных

Код курса
DEVKI
Ближайшая дата курса
7 декабря, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800

Оптимистичная конкурентность и порядок событий

Два пользователя могут менять один заказ одновременно. Держать блокировку потока на время обработки команды дорого, поэтому Event Sourcing опирается на оптимистичную конкурентность (optimistic concurrency), которую упоминает и документация KurrentDB как защиту от потерянных обновлений. Писатель требует, чтобы его событие встало ровно следующим за прочитанной версией. В PostgreSQL это выражается уникальным ограничением на пару (stream_id, stream_version), и второй писатель с той же ожидаемой версией получает ошибку 23505 unique_violation.

Проигравший писатель не прибавляет к версии единицу. Он перечитывает поток, сворачивает его и выполняет команду заново, потому что за это время состояние могло измениться так, что команда больше недопустима.

Два писателя читают поток на версии 5 и пытаются записать событие с версией 6: первый проходит, второй получает конфликт уникальности, перечитывает поток и повторяет команду

Вторая проблема касается проекторов. Глобальную позицию в PostgreSQL обычно выдаёт последовательность (identity), а она выдаёт номер в момент вставки, а не в момент фиксации. Транзакция A берёт позицию 17 и задерживается, транзакция B берёт 18 и фиксируется первой. Проектор, который читает всё, что больше последней прочитанной позиции, видит 18, сдвигает чекпойнт и позицию 17 уже не увидит никогда. С одним писателем ошибка не воспроизводится.

Закрыть её можно двумя способами. Первый сериализует запись в журнал, например через advisory lock, и платит пропускной способностью. Второй читает только события транзакций ниже горизонта, то есть уже завершённых. В PostgreSQL для этого есть идентификатор транзакции pg_current_xact_id() и граница pg_snapshot_xmin(pg_current_snapshot()), все транзакции с меньшим идентификатором уже зафиксированы или откачены. Цена второго способа в задержке, потому что долгая пишущая транзакция останавливает проектор, пока не завершится.

 

Снапшоты, версионирование событий и upcasting

Поток банковского счёта или складской позиции набирает десятки тысяч событий, и свертка с первой версии становится заметной. Снапшот (snapshot) это сохранённое состояние агрегата на версии N, после которого сворачиваются только более поздние события. Azure предлагает делать снапшоты через заданные интервалы, например каждые N событий. Снапшот остаётся кэшем, а не источником истины. После изменения логики свертки старые снапшоты выбрасывают, поэтому заводят их по замеру.

Восстановление состояния агрегата: без снапшота сворачиваются все события с первой версии, со снапшотом загружается состояние на версии N и сворачиваются только события после неё

С версионированием сложнее, потому что схема события меняется вместе с бизнесом. В демо ниже ItemAdded первой версии хранил цену целым числом в рублях, а вторая версия хранит её строкой с копейками и валютой. Переписать старые события нельзя, на неизменяемости журнала держится аудит. Поэтому событие несёт номер версии схемы, а при чтении апкастер (upcaster) поднимает старую версию до текущей, и код агрегата и проекторов видит только актуальную схему. Azure перечисляет upcasting среди стратегий наравне с терпимой десериализацией и версионированием событий, а миграцию журнала на месте называет крайней мерой.

Отдельный неудобный вопрос это персональные данные. Неизменяемый журнал конфликтует с законами о праве на забвение, и Azure прямо об этом предупреждает. Обходят конфликт архитектурно, а именно хранят персональные данные вне журнала или шифруют их ключом на пользователя и при удалении уничтожают ключ (crypto-shredding).

 

Event Sourcing против CRUD и CDC

Event Sourcing не единственный способ получить события из системы. CDC (Change Data Capture, захват изменений данных) читает журнал транзакций базы и превращает изменения строк в поток событий, но источником истины остаётся таблица. CDC уместен, когда события нужны другим системам, а приложение менять нельзя, Event Sourcing нужен, когда история сама есть модель данных.

Критерий CRUD CDC поверх CRUD Event Sourcing
Источник истины текущая строка таблицы текущая строка, события производные журнал событий, таблицы производные
История изменений нет, только отдельный аудит изменения строк без намерения пользователя полная, в терминах предметной области
Состояние на прошлую версию нет реконструкция по потоку изменений строк свертка событий до нужной версии
Конкурентность записи блокировки строк или версия строки как у CRUD ожидаемая версия потока
Чтение прямой запрос к таблице прямой запрос к таблице через модели чтения с отставанием
Эволюция схемы ALTER TABLE и миграция данных изменения таблицы приходят в поток старые события не меняются, нужны апкастеры

В продакшене хранилище событий обычно берут готовое. KurrentDB (бывший EventStoreDB, переименован с версии 25.0) это специализированная база данных потоков событий, последний патч линии 26.1 это 26.1.3 от 2 октября 2026 года. Marten это библиотека для .NET, которая хранит события в PostgreSQL и строит проекции трёх видов, inline в транзакции записи, async в фоне и live по запросу без сохранения. Axon Framework, линия 5.4, это Java-фреймворк для CQRS и Event Sourcing. Чем различаются реляционные, NoSQL и специализированные хранилища под этот паттерн, разобрано в статье Архитектура данных для реализации паттерна Event Sourcing.

Архитектура Данных

Код курса
ARMG
Ближайшая дата курса
21 декабря, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800

Когда Event Sourcing оправдан и когда нет

Паттерн окупается там, где история изменений стоит больше, чем сложность, которую он добавляет:

  • Аудит и регуляторика. Финансы, страхование, медицина, где история обязательна и должна совпадать с данными.
  • Сложная доменная логика. Много состояний и переходов, где намерение пользователя (отменил, вернул, переоформил) важнее итоговой строки.
  • Несколько моделей чтения. Одни и те же факты нужны экрану заказов, аналитике и поиску, и каждой удобна своя структура.
  • Восстановление на дату. Разбор инцидента, ответ на вопрос «что видел пользователь в момент X», пересчёт отчёта по исправленной логике.

Во всех четырёх случаях ценность несёт сама история, а не только итоговая строка. Против паттерна говорят простой CRUD без бизнес-правил, требование строгой согласованности чтения сразу после записи и команда без опыта в DDD. Azure формулирует это жёстко, для большинства систем и большинства частей системы традиционного хранения данных достаточно. Поэтому паттерн применяют к одному-двум агрегатам, где история ценна, а остальное остаётся обычными таблицами.

 

Практика, хранилище событий на PostgreSQL 18

По традиции весь код используемый в статье выкладываем на наш GitHub репозиторий

Event Sourcing на PostgreSQL from airflow import DAG from airflow.operators.bash import BashOperator from datetime import datetime with DAG( dag_id="spark_submit_demo", start_date=datetime(2025, 1, 1), schedule="@daily", catchup=False ) as dag: run = BashOperator( task_id="run_job", bash_command="spark-submit app.py" ) GitHub code example Event Sourcing на PostgreSQL

Стенд это PostgreSQL 18.6 в Docker Compose и драйвер psycopg 3.3.8 на Python 3.12.3 под Ubuntu 24.04. Каждый из пяти сценариев в прогоне шёл от 0 до 1 секунды, замер с точностью до секунды.

 

Стенд и схема журнала

Сервер описан файлом docker-compose.yml, schema.sql выполняется при первом старте на чистом томе.

# postgres 18.6 в Docker, прогнано на стенде 2026-11-06: один сервер под хранилище событий
services:
  pg:
    image: postgres:18.6
    container_name: event-sourcing-pg
    mem_limit: 1g
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: demo
      POSTGRES_DB: es
    ports:
      - "127.0.0.1:55437:5432"
    volumes:
      - pgdata:/var/lib/postgresql
      # схема журнала создаётся при первом старте на чистом томе
      - ./schema.sql:/docker-entrypoint-initdb.d/01_schema.sql:ro
    healthcheck:
      # -h 127.0.0.1: на время initdb временный сервер слушает только сокет, по TCP готов уже рабочий
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U demo -d es"]
      interval: 2s
      timeout: 3s
      retries: 30

volumes:
  pgdata:

Зависимость Python одна, она записана в requirements.txt.

# psycopg 3.3.8 с бинарной libpq, прогнано на стенде 2026-11-06
psycopg[binary]==3.3.8

Окружение и сервер поднимаются четырьмя командами.

# PostgreSQL 18.6, Docker Compose 2.40.3, Python 3.12.3, проверено на стенде 2026-11-06
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
docker compose up -d --wait
docker compose exec -T pg psql -U demo -d es -XAtc "\dt"

Журнал это таблица events. Ограничение events_stream_version_uq даёт оптимистичную конкурентность, колонка transaction_id нужна проектору, триггеры отклоняют UPDATE, DELETE и TRUNCATE.

-- postgres 18.6, прогнано на стенде 2026-11-06: схема хранилища событий на одной таблице

-- Журнал событий. Единственный источник истины, строки только добавляются.
CREATE TABLE events (
    -- глобальная позиция: сквозной номер события во всём журнале, по ней читают проекторы
    global_position bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    -- поток = один агрегат (здесь один заказ), версия = номер события внутри потока
    stream_id       text        NOT NULL,
    stream_version  integer     NOT NULL CHECK (stream_version > 0),
    event_type      text        NOT NULL,
    -- версия схемы payload: старые события не переписываются, их поднимает апкастер при чтении
    schema_version  integer     NOT NULL DEFAULT 1,
    payload         jsonb       NOT NULL,
    metadata        jsonb       NOT NULL DEFAULT '{}'::jsonb,
    -- идентификатор транзакции записи: нужен проектору, чтобы не пропускать поздно зафиксированные события
    transaction_id  xid8        NOT NULL DEFAULT pg_current_xact_id(),
    recorded_at     timestamptz NOT NULL DEFAULT clock_timestamp(),
    -- оптимистичная конкурентность: две записи с одной версией в одном потоке невозможны
    CONSTRAINT events_stream_version_uq UNIQUE (stream_id, stream_version)
);

CREATE INDEX events_tx_position_idx ON events (transaction_id, global_position);

-- Журнал неизменяем: UPDATE, DELETE и TRUNCATE отклоняются триггером.
CREATE FUNCTION events_forbid_change() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
    RAISE EXCEPTION 'журнал событий только на добавление: % запрещён', TG_OP
        USING ERRCODE = 'restrict_violation';
END;
$$;

CREATE TRIGGER events_append_only
    BEFORE UPDATE OR DELETE ON events
    FOR EACH ROW EXECUTE FUNCTION events_forbid_change();

CREATE TRIGGER events_no_truncate
    BEFORE TRUNCATE ON events
    FOR EACH STATEMENT EXECUTE FUNCTION events_forbid_change();

-- Снапшот: кэш состояния агрегата на версии N. Его можно стереть и построить заново из журнала.
CREATE TABLE snapshots (
    stream_id      text        PRIMARY KEY,
    stream_version integer     NOT NULL,
    state          jsonb       NOT NULL,
    taken_at       timestamptz NOT NULL DEFAULT clock_timestamp()
);

-- Чекпойнт проектора: до какого места журнала он дочитал.
CREATE TABLE projection_checkpoints (
    projection      text   PRIMARY KEY,
    last_tx         xid8   NOT NULL DEFAULT '0',
    last_position   bigint NOT NULL DEFAULT 0
);

-- Модель чтения: сводка по заказу для экрана «Мои заказы». Производная от журнала.
CREATE TABLE order_summary (
    order_id    text    PRIMARY KEY,
    customer    text    NOT NULL,
    status      text    NOT NULL,
    lines       jsonb   NOT NULL DEFAULT '{}'::jsonb,
    items_count integer NOT NULL DEFAULT 0,
    total       numeric(12, 2) NOT NULL DEFAULT 0,
    -- версия потока, до которой модель уже обновлена: защита от повторной доставки
    version     integer NOT NULL
);

 

Запись событий и восстановление состояния

Агрегат заказа живёт в order.py. Команды проверяют инварианты и возвращают события, apply применяет одно событие, fold сворачивает список.

# Python 3.12, агрегат заказа без внешних зависимостей, прогнано на стенде 2026-11-06
"""Агрегат «заказ»: команды решают, какие события записать, свертка восстанавливает состояние.

Состояние нигде не хранится как источник истины. Его всегда можно получить заново,
свернув события потока по порядку версий.
"""
from decimal import Decimal


class DomainError(Exception):
    """Команда нарушает инвариант агрегата и отклоняется до записи в журнал."""


def initial_state(order_id: str) -> dict:
    return {"order_id": order_id, "status": None, "customer": None, "lines": {}, "version": 0}


def apply(state: dict, event_type: str, payload: dict, version: int) -> dict:
    """Одно событие меняет состояние. Здесь нет проверок: событие уже случилось."""
    s = {**state, "lines": dict(state["lines"]), "version": version}
    if event_type == "OrderCreated":
        s["status"] = "new"
        s["customer"] = payload["customer"]
    elif event_type == "ItemAdded":
        line = s["lines"].get(payload["sku"], {"qty": 0, "price": payload["price"]})
        s["lines"][payload["sku"]] = {"qty": line["qty"] + payload["qty"], "price": payload["price"]}
    elif event_type == "ItemRemoved":
        s["lines"].pop(payload["sku"], None)
    elif event_type == "OrderPaid":
        s["status"] = "paid"
    elif event_type == "OrderShipped":
        s["status"] = "shipped"
    else:
        raise ValueError(f"неизвестный тип события {event_type}")
    return s


def fold(events, state: dict) -> dict:
    """Свертка: левый fold списка событий поверх начального состояния или снапшота."""
    for e in events:
        state = apply(state, e.event_type, e.payload, e.stream_version)
    return state


def total(state: dict) -> Decimal:
    return sum((Decimal(l["price"]) * l["qty"] for l in state["lines"].values()), Decimal("0.00"))


# ---- команды: проверяют инварианты на текущем состоянии и возвращают новые события ----

def create(state: dict, customer: str) -> list[tuple[str, dict]]:
    if state["status"] is not None:
        raise DomainError(f"заказ {state['order_id']} уже создан")
    return [("OrderCreated", {"customer": customer})]


def add_item(state: dict, sku: str, qty: int, price: str) -> list[tuple[str, dict]]:
    if state["status"] != "new":
        raise DomainError(f"заказ в статусе {state['status']}, позиции менять нельзя")
    if qty <= 0:
        raise DomainError("количество должно быть больше нуля")
    return [("ItemAdded", {"sku": sku, "qty": qty, "price": price, "currency": "RUB"})]


def remove_item(state: dict, sku: str) -> list[tuple[str, dict]]:
    if state["status"] != "new":
        raise DomainError(f"заказ в статусе {state['status']}, позиции менять нельзя")
    if sku not in state["lines"]:
        raise DomainError(f"позиции {sku} в заказе нет")
    return [("ItemRemoved", {"sku": sku})]


def pay(state: dict, amount: str) -> list[tuple[str, dict]]:
    if state["status"] != "new":
        raise DomainError(f"заказ в статусе {state['status']}, оплатить нельзя")
    if not state["lines"]:
        raise DomainError("пустой заказ не оплачивается")
    if Decimal(amount) != total(state):
        raise DomainError(f"сумма оплаты {amount} не равна сумме заказа {total(state)}")
    return [("OrderPaid", {"amount": amount})]


def ship(state: dict, carrier: str) -> list[tuple[str, dict]]:
    if state["status"] != "paid":
        raise DomainError(f"заказ в статусе {state['status']}, отгрузить нельзя")
    return [("OrderShipped", {"carrier": carrier})]

В event_store.py функция append пишет события одной транзакцией и превращает 23505 в ConcurrencyError. Здесь же апкастер и два варианта чтения журнала, наивный и по горизонту транзакций.

# psycopg 3.3.8, postgres 18.6 в Docker, прогнано на стенде 2026-11-06
"""Хранилище событий на одной таблице PostgreSQL: запись с ожидаемой версией, чтение потока,
чтение журнала для проектора и апкастеры старых версий событий."""
from dataclasses import dataclass
from decimal import Decimal

import psycopg
from psycopg.types.json import Jsonb

# Текущая версия схемы для каждого типа события. Новые события пишутся только в ней.
CURRENT_SCHEMA = {"ItemAdded": 2}


class ConcurrencyError(Exception):
    """Кто-то успел записать в поток раньше: ожидаемая версия устарела."""

    def __init__(self, stream_id: str, expected_version: int):
        super().__init__(f"поток {stream_id}: ожидали версию {expected_version}, она уже занята")
        self.stream_id = stream_id
        self.expected_version = expected_version


@dataclass(frozen=True)
class Event:
    global_position: int
    stream_id: str
    stream_version: int
    event_type: str
    schema_version: int
    payload: dict
    transaction_id: int = 0


# ---- апкастеры: поднимают старую версию payload до текущей при чтении, журнал не трогают ----

def _item_added_v1_to_v2(p: dict) -> dict:
    # v1: {"sku", "qty", "price": 1290} цена целым числом в рублях
    # v2: {"sku", "qty", "price": "1290.00", "currency": "RUB"}
    return {"sku": p["sku"], "qty": p["qty"],
            "price": str(Decimal(p["price"]).quantize(Decimal("0.01"))), "currency": "RUB"}


UPCASTERS = {("ItemAdded", 1): (2, _item_added_v1_to_v2)}


def upcast(event_type: str, schema_version: int, payload: dict) -> tuple[int, dict]:
    # цепочка: v1 -> v2 -> ... пока для пары (тип, версия) есть апкастер
    while (event_type, schema_version) in UPCASTERS:
        schema_version, fn = UPCASTERS[(event_type, schema_version)]
        payload = fn(payload)
    return schema_version, payload


def _row_to_event(row) -> Event:
    pos, stream_id, version, etype, schema, payload, tx = row
    schema, payload = upcast(etype, schema, payload)
    return Event(pos, stream_id, version, etype, schema, payload, int(tx))


_COLUMNS = ("global_position, stream_id, stream_version, event_type, schema_version, payload, "
            "transaction_id::text")


# ---- запись ----

def insert_events(cur, stream_id: str, expected_version: int, events, metadata=None) -> int:
    """INSERT без управления транзакцией: версии идут подряд после ожидаемой."""
    rows = [(stream_id, expected_version + i, etype, CURRENT_SCHEMA.get(etype, 1),
             Jsonb(payload), Jsonb(metadata or {}))
            for i, (etype, payload) in enumerate(events, start=1)]
    cur.executemany(
        "INSERT INTO events (stream_id, stream_version, event_type, schema_version, payload, metadata) "
        "VALUES (%s, %s, %s, %s, %s, %s)", rows)
    return expected_version + len(rows)


def append(conn: psycopg.Connection, stream_id: str, expected_version: int, events,
           metadata=None) -> int:
    """Дописать события в поток одной транзакцией. Возвращает новую версию потока.

    Проверку версии делает уникальный индекс (stream_id, stream_version): если другой
    писатель уже занял версию expected_version + 1, вставка падает с 23505.
    """
    try:
        with conn.transaction(), conn.cursor() as cur:
            return insert_events(cur, stream_id, expected_version, events, metadata)
    except psycopg.errors.UniqueViolation as e:
        raise ConcurrencyError(stream_id, expected_version) from e


# ---- чтение потока ----

def read_stream(conn: psycopg.Connection, stream_id: str, after_version: int = 0,
                to_version: int | None = None) -> list[Event]:
    sql = f"SELECT {_COLUMNS} FROM events WHERE stream_id = %s AND stream_version > %s"
    params: list = [stream_id, after_version]
    if to_version is not None:
        sql += " AND stream_version <= %s"
        params.append(to_version)
    rows = conn.execute(sql + " ORDER BY stream_version", params).fetchall()
    return [_row_to_event(r) for r in rows]


# ---- чтение журнала проектором ----

def read_all_naive(conn: psycopg.Connection, after_position: int, limit: int = 1000) -> list[Event]:
    """Наивно: всё, что больше последней прочитанной позиции.

    Пропускает событие, если его транзакция взяла позицию раньше соседней, а зафиксировалась позже.
    """
    rows = conn.execute(
        f"SELECT {_COLUMNS} FROM events WHERE global_position > %s ORDER BY global_position LIMIT %s",
        [after_position, limit]).fetchall()
    return [_row_to_event(r) for r in rows]


def read_all_safe(conn: psycopg.Connection, after_tx: int, after_position: int,
                  limit: int = 1000) -> list[Event]:
    """Только события транзакций ниже горизонта: xid меньше xmin текущего снимка.

    Все такие транзакции уже завершены, новых с меньшим xid не появится, поэтому порядок
    (transaction_id, global_position) растёт без дыр. Цена: пока открыта долгая пишущая
    транзакция, проектор стоит и ждёт её.
    """
    rows = conn.execute(
        f"SELECT {_COLUMNS} FROM events "
        "WHERE (transaction_id, global_position) > (%s::xid8, %s) "
        "  AND transaction_id < pg_snapshot_xmin(pg_current_snapshot()) "
        "ORDER BY transaction_id, global_position LIMIT %s",
        [str(after_tx), after_position, limit]).fetchall()
    return [_row_to_event(r) for r in rows]

Сценарии собраны в es_demo.py, функция handle повторяет цепочку из раздела о принципе работы.

# psycopg 3.3.8, postgres 18.6 в Docker, прогнано на стенде 2026-11-06
"""Демо Event Sourcing на PostgreSQL: запись и свертка, конфликт писателей, проекция,
снапшот, апкастер.

Запуск: python es_demo.py all | append | conflict | projection | snapshot | upcast
Адрес базы берётся из ES_DSN, по умолчанию postgresql://demo:demo@127.0.0.1:55437/es
"""
import os
import statistics
import sys
import time

import psycopg
from psycopg.types.json import Jsonb

import order
import projector
from event_store import (ConcurrencyError, append, insert_events, read_all_naive,
                         read_all_safe, read_stream)

DSN = os.environ.get("ES_DSN", "postgresql://demo:demo@127.0.0.1:55437/es")


def connect() -> psycopg.Connection:
    return psycopg.connect(DSN, autocommit=True)


def load(conn, order_id: str, to_version: int | None = None) -> dict:
    """Восстановить агрегат: прочитать поток и свернуть события по порядку версий."""
    return order.fold(read_stream(conn, order_id, to_version=to_version), order.initial_state(order_id))


def handle(conn, order_id: str, command, *args) -> int:
    """Обработчик команды: загрузить, проверить инварианты, дописать с ожидаемой версией."""
    state = load(conn, order_id)
    return append(conn, order_id, state["version"], command(state, *args),
                  metadata={"command": command.__name__})


def show_state(label: str, s: dict) -> None:
    lines = ", ".join(f"{k}×{v['qty']} по {v['price']}" for k, v in sorted(s["lines"].items()))
    print(f"  {label}: версия {s['version']}, статус {s['status']}, позиции [{lines}], "
          f"сумма {order.total(s)}")


# ---------------------------------------------------------------------------------------------

def demo_append(conn) -> None:
    print("\n=== 1. APPEND: запись событий и восстановление состояния ===")
    oid = "order-1001"
    handle(conn, oid, order.create, "alice")
    handle(conn, oid, order.add_item, "book", 2, "1290.00")
    handle(conn, oid, order.add_item, "lamp", 1, "3490.00")
    handle(conn, oid, order.remove_item, "lamp")
    handle(conn, oid, order.add_item, "pen", 3, "150.00")
    s = load(conn, oid)
    handle(conn, oid, order.pay, str(order.total(s)))
    handle(conn, oid, order.ship, "cdek")

    print("Журнал потока", oid)
    for r in conn.execute(
            "SELECT global_position, stream_version, event_type, schema_version, payload::text "
            "FROM events WHERE stream_id = %s ORDER BY stream_version", [oid]):
        print(f"  pos={r[0]:<3} v={r[1]} {r[2]:<13} schema=v{r[3]} {r[4]}")

    show_state("состояние сейчас (свертка 7 событий)", load(conn, oid))
    show_state("состояние на версии 3 (свертка первых 3)", load(conn, oid, to_version=3))
    show_state("состояние на версии 4 (после удаления lamp)", load(conn, oid, to_version=4))

    print("Команда против инварианта: добавить позицию в отгруженный заказ")
    try:
        handle(conn, oid, order.add_item, "mug", 1, "590.00")
    except order.DomainError as e:
        print("  отклонено до записи:", e)

    print("Попытка исправить историю прямо в таблице")
    for sql in ("UPDATE events SET payload = jsonb_set(payload, '{qty}', '5') "
                "WHERE stream_id = 'order-1001' AND stream_version = 2",
                "DELETE FROM events WHERE stream_id = 'order-1001' AND stream_version = 4",
                "TRUNCATE events"):
        try:
            conn.execute(sql)
        except psycopg.Error as e:
            print(f"  {sql.split()[0]}: {e.sqlstate} {e.diag.message_primary}")
    print("  событий в потоке после попыток:",
          conn.execute("SELECT count(*) FROM events WHERE stream_id = %s", [oid]).fetchone()[0])


def demo_conflict(conn) -> None:
    print("\n=== 2. CONFLICT: оптимистичная конкурентность ===")
    oid = "order-2002"
    handle(conn, oid, order.create, "bob")
    handle(conn, oid, order.add_item, "book", 1, "1290.00")
    w1, w2 = connect(), connect()

    print("Пара А: два писателя добавляют разные позиции")
    s1, s2 = load(w1, oid), load(w2, oid)
    print(f"  писатель 1 прочитал версию {s1['version']}, писатель 2 прочитал версию {s2['version']}")
    v = append(w1, oid, s1["version"], order.add_item(s1, "lamp", 1, "3490.00"))
    print(f"  писатель 1 записал ItemAdded(lamp) с ожидаемой версией {s1['version']} -> версия {v}")
    try:
        append(w2, oid, s2["version"], order.add_item(s2, "pen", 2, "150.00"))
    except ConcurrencyError as e:
        print(f"  писатель 2: {e.__cause__.sqlstate} {type(e.__cause__).__name__}: {e}")
        s2 = load(w2, oid)
        print(f"  писатель 2 перечитал поток: версия {s2['version']}, позиции {sorted(s2['lines'])}")
        v = append(w2, oid, s2["version"], order.add_item(s2, "pen", 2, "150.00"))
        print(f"  писатель 2 повторил команду -> версия {v}")

    print("Пара Б: писатель 1 оплачивает, писатель 2 в это время добавляет позицию")
    s1, s2 = load(w1, oid), load(w2, oid)
    print(f"  оба прочитали версию {s1['version']}")
    v = append(w1, oid, s1["version"], order.pay(s1, str(order.total(s1))))
    print(f"  писатель 1 записал OrderPaid -> версия {v}")
    try:
        append(w2, oid, s2["version"], order.add_item(s2, "mug", 1, "590.00"))
    except ConcurrencyError as e:
        print(f"  писатель 2: {e.__cause__.sqlstate} {type(e.__cause__).__name__}: {e}")
        s2 = load(w2, oid)
        print(f"  писатель 2 перечитал поток: версия {s2['version']}, статус {s2['status']}")
        try:
            append(w2, oid, s2["version"], order.add_item(s2, "mug", 1, "590.00"))
        except order.DomainError as de:
            print("  повтор команды отклонён инвариантом:", de)
    show_state("итог", load(conn, oid))
    for c in (w1, w2):
        c.close()


def demo_projection(conn) -> None:
    print("\n=== 3. PROJECTION: модель чтения, повторная доставка, пересборка ===")
    oid = "order-3003"
    handle(conn, oid, order.create, "carol")
    handle(conn, oid, order.add_item, "lamp", 2, "3490.00")

    projector.reset(conn, drop_model=True)
    n, a = projector.catch_up(conn)
    print(f"Первый проход: прочитано {n}, применено {a}")
    cp = conn.execute("SELECT last_tx::text, last_position FROM projection_checkpoints").fetchone()
    print(f"  чекпойнт: last_tx={cp[0]}, last_position={cp[1]}")
    n, a = projector.catch_up(conn)
    print(f"Второй проход без новых событий: прочитано {n}, применено {a}")

    summary_sql = ("SELECT order_id, customer, status, items_count, total, version "
                   "FROM order_summary ORDER BY order_id")
    before = conn.execute(summary_sql).fetchall()
    print("Модель чтения order_summary:")
    for r in before:
        print(f"  {r[0]} {r[1]:<6} {r[2]:<8} позиций={r[3]} сумма={r[4]} версия={r[5]}")

    projector.reset(conn, drop_model=False)
    n, a = projector.catch_up(conn)
    print(f"Чекпойнт сброшен, модель оставлена (повторная доставка всего журнала): "
          f"прочитано {n}, применено {a}")

    projector.reset(conn, drop_model=True)
    n, a = projector.catch_up(conn)
    after = conn.execute(summary_sql).fetchall()
    print(f"Пересборка с нуля (TRUNCATE модели и чекпойнта): прочитано {n}, применено {a}, "
          f"модель совпала с прежней: {before == after}")

    print("Ловушка глобальной позиции: транзакция A взяла позицию раньше B, а зафиксировалась позже")
    a_conn, b_conn, reader = connect(), connect(), connect()
    last = conn.execute("SELECT max(global_position) FROM events").fetchone()[0]
    last_tx = int(conn.execute("SELECT max(transaction_id)::text FROM events").fetchone()[0])
    naive_seen, safe_seen = [], []
    naive_pos, safe_cp = last, (last_tx, last)

    def poll(step: str) -> None:
        nonlocal naive_pos, safe_cp
        got_n = read_all_naive(reader, naive_pos)
        got_s = read_all_safe(reader, *safe_cp)
        if got_n:
            naive_pos = got_n[-1].global_position
        if got_s:
            safe_cp = (got_s[-1].transaction_id, got_s[-1].global_position)
        naive_seen.extend(e.global_position for e in got_n)
        safe_seen.extend(e.global_position for e in got_s)
        print(f"  {step}: наивный прочитал {[e.global_position for e in got_n]}, чекпойнт {naive_pos}; "
              f"по горизонту прочитал {[e.global_position for e in got_s]}")

    with a_conn.transaction(), a_conn.cursor() as cur:
        insert_events(cur, "order-4004", 0, order.create(order.initial_state("order-4004"), "dave"))
        pos_a = cur.execute("SELECT max(global_position) FROM events").fetchone()[0]
        print(f"  A: вставил OrderCreated(order-4004), позиция {pos_a}, транзакция открыта")
        append(b_conn, "order-5005", 0, order.create(order.initial_state("order-5005"), "erin"))
        pos_b = b_conn.execute("SELECT max(global_position) FROM events").fetchone()[0]
        print(f"  B: вставил OrderCreated(order-5005), позиция {pos_b}, COMMIT")
        poll("опрос 1, A ещё открыта")
    print("  A: COMMIT")
    poll("опрос 2, обе зафиксированы")
    poll("опрос 3")
    print(f"  итог: наивный проектор увидел {naive_seen}, пропущена позиция {pos_a}: "
          f"{pos_a not in naive_seen}; по горизонту увидел {safe_seen}")
    for c in (a_conn, b_conn, reader):
        c.close()


def demo_snapshot(conn) -> None:
    print("\n=== 4. SNAPSHOT: полная свертка против снапшота плюс хвост ===")
    oid = "order-6006"
    n_bulk, n_tail = 10_000, 20
    # длинный поток: позиции по кругу добавляются и удаляются, состояние остаётся маленьким
    bulk = [("OrderCreated", {"customer": "frank"})]
    for i in range(1, n_bulk):
        sku = f"sku-{i % 50:02d}"
        if i % 7 == 0:
            bulk.append(("ItemRemoved", {"sku": sku}))
        else:
            bulk.append(("ItemAdded", {"sku": sku, "qty": 1, "price": "100.00", "currency": "RUB"}))
    t = time.perf_counter()
    append(conn, oid, 0, bulk)
    print(f"Записано {n_bulk} событий одной транзакцией за {(time.perf_counter() - t) * 1000:.0f} мс")

    s = load(conn, oid)
    conn.execute("INSERT INTO snapshots (stream_id, stream_version, state) VALUES (%s, %s, %s) "
                 "ON CONFLICT (stream_id) DO UPDATE SET stream_version = EXCLUDED.stream_version, "
                 "state = EXCLUDED.state", [oid, s["version"], Jsonb(s)])
    print(f"Снапшот сохранён на версии {s['version']}")
    tail = [("ItemAdded", {"sku": f"tail-{i:02d}", "qty": 1, "price": "10.00", "currency": "RUB"})
            for i in range(n_tail)]
    append(conn, oid, s["version"], tail)

    def full():
        return load(conn, oid)

    def with_snapshot():
        version, state = conn.execute(
            "SELECT stream_version, state FROM snapshots WHERE stream_id = %s", [oid]).fetchone()
        return order.fold(read_stream(conn, oid, after_version=version), state)

    def measure(fn, runs=7):
        times, result = [], None
        for _ in range(runs):
            t = time.perf_counter()
            result = fn()
            times.append((time.perf_counter() - t) * 1000)
        return statistics.median(times), result

    full()  # прогрев кэша страниц и соединения
    t_full, s_full = measure(full)
    t_snap, s_snap = measure(with_snapshot)
    print(f"Полная свертка {s_full['version']} событий: медиана {t_full:.1f} мс из 7 запусков")
    print(f"Снапшот на версии {s['version']} плюс хвост {n_tail} событий: медиана {t_snap:.1f} мс")
    print(f"Ускорение: {t_full / t_snap:.0f}×, состояния совпали: {s_full == s_snap}")
    print(f"  состояние: версия {s_snap['version']}, статус {s_snap['status']}, "
          f"разных позиций {len(s_snap['lines'])}, сумма {order.total(s_snap)}")


def demo_upcast(conn) -> None:
    print("\n=== 5. UPCAST: старая версия события поднимается при чтении ===")
    oid = "order-7007"
    # старый код писал ItemAdded v1: цена целым числом в рублях, без валюты
    conn.execute(
        "INSERT INTO events (stream_id, stream_version, event_type, schema_version, payload) VALUES "
        "(%s, 1, 'OrderCreated', 1, '{\"customer\": \"grace\"}'), "
        "(%s, 2, 'ItemAdded', 1, '{\"sku\": \"book\", \"qty\": 2, \"price\": 1290}')", [oid, oid])
    # новый код пишет только v2
    handle(conn, oid, order.add_item, "pen", 3, "150.50")

    count_sql = ("SELECT schema_version, count(*) FROM events "
                 "WHERE event_type = 'ItemAdded' AND stream_id = %s GROUP BY 1 ORDER BY 1")
    before = conn.execute(count_sql, [oid]).fetchall()
    print("В журнале как записано:")
    for r in conn.execute("SELECT stream_version, event_type, schema_version, payload::text FROM events "
                          "WHERE stream_id = %s ORDER BY stream_version", [oid]):
        print(f"  v={r[0]} {r[1]:<13} schema=v{r[2]} {r[3]}")
    print("После чтения через апкастер:")
    for e in read_stream(conn, oid):
        print(f"  v={e.stream_version} {e.event_type:<13} schema=v{e.schema_version} {e.payload}")
    show_state("состояние", load(conn, oid))
    after = conn.execute(count_sql, [oid]).fetchall()
    print(f"ItemAdded по версиям схемы в журнале до чтения {before}, после {after}, "
          f"журнал не изменился: {before == after}")


DEMOS = {"append": demo_append, "conflict": demo_conflict, "projection": demo_projection,
         "snapshot": demo_snapshot, "upcast": demo_upcast}


def main() -> int:
    mode = sys.argv[1] if len(sys.argv) > 1 else "all"
    if mode != "all" and mode not in DEMOS:
        print(__doc__)
        return 2
    with connect() as conn:
        print("PostgreSQL:", conn.execute("SHOW server_version").fetchone()[0],
              "| psycopg", psycopg.__version__)
        for name, fn in DEMOS.items():
            if mode in ("all", name):
                fn(conn)
    return 0


if __name__ == "__main__":
    sys.exit(main())

Каждый сценарий запускается своей командой. Первый запускается командой .venv/bin/python es_demo.py append, остальные отличаются только именем сценария в конце.

# вывод прогона на стенде 2026-11-06, PostgreSQL 18.6, psycopg 3.3.8, фрагмент run_output.txt
=== 1. APPEND: запись событий и восстановление состояния ===
Журнал потока order-1001
  pos=1   v=1 OrderCreated  schema=v1 {"customer": "alice"}
  pos=2   v=2 ItemAdded     schema=v2 {"qty": 2, "sku": "book", "price": "1290.00", "currency": "RUB"}
  pos=3   v=3 ItemAdded     schema=v2 {"qty": 1, "sku": "lamp", "price": "3490.00", "currency": "RUB"}
  pos=4   v=4 ItemRemoved   schema=v1 {"sku": "lamp"}
  pos=5   v=5 ItemAdded     schema=v2 {"qty": 3, "sku": "pen", "price": "150.00", "currency": "RUB"}
  pos=6   v=6 OrderPaid     schema=v1 {"amount": "3030.00"}
  pos=7   v=7 OrderShipped  schema=v1 {"carrier": "cdek"}
  состояние сейчас (свертка 7 событий): версия 7, статус shipped, позиции [book×2 по 1290.00, pen×3 по 150.00], сумма 3030.00
  состояние на версии 3 (свертка первых 3): версия 3, статус new, позиции [book×2 по 1290.00, lamp×1 по 3490.00], сумма 6070.00
  состояние на версии 4 (после удаления lamp): версия 4, статус new, позиции [book×2 по 1290.00], сумма 2580.00
Команда против инварианта: добавить позицию в отгруженный заказ
  отклонено до записи: заказ в статусе shipped, позиции менять нельзя
Попытка исправить историю прямо в таблице
  UPDATE: 23001 журнал событий только на добавление: UPDATE запрещён
  DELETE: 23001 журнал событий только на добавление: DELETE запрещён
  TRUNCATE: 23001 журнал событий только на добавление: TRUNCATE запрещён
  событий в потоке после попыток: 7

Состояние на третьей версии ещё содержит лампу за 3490.00, которую удалило четвёртое событие, поэтому сумма там 6070.00 против итоговых 3030.00.

 

Конфликт двух писателей

Сценарий conflict открывает два соединения к потоку order-2002.

# вывод прогона на стенде 2026-11-06, PostgreSQL 18.6, psycopg 3.3.8, фрагмент run_output.txt
=== 2. CONFLICT: оптимистичная конкурентность ===
Пара А: два писателя добавляют разные позиции
  писатель 1 прочитал версию 2, писатель 2 прочитал версию 2
  писатель 1 записал ItemAdded(lamp) с ожидаемой версией 2 -> версия 3
  писатель 2: 23505 UniqueViolation: поток order-2002: ожидали версию 2, она уже занята
  писатель 2 перечитал поток: версия 3, позиции ['book', 'lamp']
  писатель 2 повторил команду -> версия 4
Пара Б: писатель 1 оплачивает, писатель 2 в это время добавляет позицию
  оба прочитали версию 4
  писатель 1 записал OrderPaid -> версия 5
  писатель 2: 23505 UniqueViolation: поток order-2002: ожидали версию 4, она уже занята
  писатель 2 перечитал поток: версия 5, статус paid
  повтор команды отклонён инвариантом: заказ в статусе paid, позиции менять нельзя
  итог: версия 5, статус paid, позиции [book×1 по 1290.00, lamp×1 по 3490.00, pen×2 по 150.00], сумма 5080.00

В паре А повтор после перечитывания проходит, и поток получает версию 4. В паре Б повтор отклоняет уже не база, а инвариант агрегата, потому что заказ оплачен. Если бы второй писатель просто прибавил единицу к версии, позиция попала бы в оплаченный заказ.

 

Проекция и пересборка модели чтения

Проектор в projector.py обновляет order_summary и чекпойнт одной транзакцией, а повторно доставленное событие отсекает по версии потока.

# psycopg 3.3.8, postgres 18.6 в Docker, прогнано на стенде 2026-11-06
"""Асинхронный проектор: читает журнал после чекпойнта и обновляет модель чтения order_summary.

Модель чтения и чекпойнт обновляются в одной транзакции: упал посередине, значит не сдвинулся
ни чекпойнт, ни модель. Повторно доставленное событие отсекается по версии потока.
"""
from decimal import Decimal

import psycopg
from psycopg.types.json import Jsonb

from event_store import Event, read_all_safe

NAME = "order_summary"


def _apply(cur, e: Event) -> bool:
    """Применить событие к модели чтения. False, если событие уже было учтено."""
    row = cur.execute("SELECT customer, status, lines, version FROM order_summary "
                      "WHERE order_id = %s FOR UPDATE", [e.stream_id]).fetchone()
    if row is not None and e.stream_version <= row[3]:
        return False  # повторная доставка: эта версия потока уже в модели
    if e.event_type == "OrderCreated":
        customer, status, lines = e.payload["customer"], "new", {}
    else:
        customer, status, lines = row[0], row[1], dict(row[2])
        if e.event_type == "ItemAdded":
            qty = lines.get(e.payload["sku"], {}).get("qty", 0) + e.payload["qty"]
            lines[e.payload["sku"]] = {"qty": qty, "price": e.payload["price"]}
        elif e.event_type == "ItemRemoved":
            lines.pop(e.payload["sku"], None)
        elif e.event_type == "OrderPaid":
            status = "paid"
        elif e.event_type == "OrderShipped":
            status = "shipped"
    items = sum(l["qty"] for l in lines.values())
    amount = sum((Decimal(l["price"]) * l["qty"] for l in lines.values()), Decimal("0.00"))
    cur.execute(
        "INSERT INTO order_summary (order_id, customer, status, lines, items_count, total, version) "
        "VALUES (%s, %s, %s, %s, %s, %s, %s) "
        "ON CONFLICT (order_id) DO UPDATE SET status = EXCLUDED.status, lines = EXCLUDED.lines, "
        "items_count = EXCLUDED.items_count, total = EXCLUDED.total, version = EXCLUDED.version",
        [e.stream_id, customer, status, Jsonb(lines), items, amount, e.stream_version])
    return True


def run_once(conn: psycopg.Connection, batch: int = 1000) -> tuple[int, int]:
    """Один проход: прочитать пачку после чекпойнта, применить, сдвинуть чекпойнт.

    Возвращает (прочитано, применено).
    """
    with conn.transaction(), conn.cursor() as cur:
        cur.execute("INSERT INTO projection_checkpoints (projection) VALUES (%s) "
                    "ON CONFLICT DO NOTHING", [NAME])
        last_tx, last_pos = cur.execute(
            "SELECT last_tx::text, last_position FROM projection_checkpoints "
            "WHERE projection = %s FOR UPDATE", [NAME]).fetchone()
        events = read_all_safe(conn, int(last_tx), last_pos, batch)
        applied = sum(_apply(cur, e) for e in events)
        if events:
            cur.execute("UPDATE projection_checkpoints SET last_tx = %s::xid8, last_position = %s "
                        "WHERE projection = %s",
                        [str(events[-1].transaction_id), events[-1].global_position, NAME])
    return len(events), applied


def catch_up(conn: psycopg.Connection) -> tuple[int, int]:
    """Крутить проходы, пока журнал не кончится."""
    read_total = applied_total = 0
    while True:
        n, a = run_once(conn)
        read_total, applied_total = read_total + n, applied_total + a
        if n == 0:
            return read_total, applied_total


def reset(conn: psycopg.Connection, drop_model: bool) -> None:
    """Сбросить чекпойнт; с drop_model ещё и стереть модель чтения для пересборки с нуля."""
    with conn.transaction():
        if drop_model:
            conn.execute("TRUNCATE order_summary")
        conn.execute("DELETE FROM projection_checkpoints WHERE projection = %s", [NAME])

Сценарий projection дополнительно воспроизводит ловушку глобальной позиции на трёх соединениях.

# вывод прогона на стенде 2026-11-06, PostgreSQL 18.6, psycopg 3.3.8, фрагмент run_output.txt
=== 3. PROJECTION: модель чтения, повторная доставка, пересборка ===
Первый проход: прочитано 14, применено 14
  чекпойнт: last_tx=780, last_position=16
Второй проход без новых событий: прочитано 0, применено 0
Модель чтения order_summary:
  order-1001 alice  shipped  позиций=5 сумма=3030.00 версия=7
  order-2002 bob    paid     позиций=4 сумма=5080.00 версия=5
  order-3003 carol  new      позиций=2 сумма=6980.00 версия=2
Чекпойнт сброшен, модель оставлена (повторная доставка всего журнала): прочитано 14, применено 0
Пересборка с нуля (TRUNCATE модели и чекпойнта): прочитано 14, применено 14, модель совпала с прежней: True
Ловушка глобальной позиции: транзакция A взяла позицию раньше B, а зафиксировалась позже
  A: вставил OrderCreated(order-4004), позиция 17, транзакция открыта
  B: вставил OrderCreated(order-5005), позиция 18, COMMIT
  опрос 1, A ещё открыта: наивный прочитал [18], чекпойнт 18; по горизонту прочитал []
  A: COMMIT
  опрос 2, обе зафиксированы: наивный прочитал [], чекпойнт 18; по горизонту прочитал [17, 18]
  опрос 3: наивный прочитал [], чекпойнт 18; по горизонту прочитал []
  итог: наивный проектор увидел [18], пропущена позиция 17: True; по горизонту увидел [17, 18]

Проектор по горизонту на первом опросе не прочитал ничего и забрал обе позиции после фиксации A, это задержка, а не потеря.

 

Снапшот против полной свертки

Сценарий snapshot пишет в поток 10 000 событий одной транзакцией, сохраняет снапшот на версии 10 000 и дописывает хвост из 20 событий.

# вывод прогона на стенде 2026-11-06, PostgreSQL 18.6, psycopg 3.3.8, фрагмент run_output.txt
=== 4. SNAPSHOT: полная свертка против снапшота плюс хвост ===
Записано 10000 событий одной транзакцией за 459 мс
Снапшот сохранён на версии 10000
Полная свертка 10020 событий: медиана 98.7 мс из 7 запусков
Снапшот на версии 10000 плюс хвост 20 событий: медиана 1.1 мс
Ускорение: 92×, состояния совпали: True
  состояние: версия 10020, статус new, разных позиций 63, сумма 15200.00

Полная свертка 10 020 событий заняла около 99 мс, снапшот с хвостом 1.1 мс, то есть примерно в 90 раз быстрее, а точная кратность плавает между прогонами. Замер включает чтение из базы по localhost и свертку в Python.

 

Апкастер для старой версии события

Сценарий upcast вставляет напрямую ItemAdded первой версии, как его записал бы старый код, и добавляет вторую позицию через текущий обработчик.

# вывод прогона на стенде 2026-11-06, PostgreSQL 18.6, psycopg 3.3.8, фрагмент run_output.txt
=== 5. UPCAST: старая версия события поднимается при чтении ===
В журнале как записано:
  v=1 OrderCreated  schema=v1 {"customer": "grace"}
  v=2 ItemAdded     schema=v1 {"qty": 2, "sku": "book", "price": 1290}
  v=3 ItemAdded     schema=v2 {"qty": 3, "sku": "pen", "price": "150.50", "currency": "RUB"}
После чтения через апкастер:
  v=1 OrderCreated  schema=v1 {'customer': 'grace'}
  v=2 ItemAdded     schema=v2 {'sku': 'book', 'qty': 2, 'price': '1290.00', 'currency': 'RUB'}
  v=3 ItemAdded     schema=v2 {'qty': 3, 'sku': 'pen', 'price': '150.50', 'currency': 'RUB'}
  состояние: версия 3, статус new, позиции [book×2 по 1290.00, pen×3 по 150.50], сумма 3031.50
ItemAdded по версиям схемы в журнале до чтения [(1, 1), (2, 1)], после [(1, 1), (2, 1)], журнал не изменился: True

После всех сценариев в журнале 10 039 событий, а таблица events вместе с индексами занимает 2568 kB.

 

Заключение

Event Sourcing хранит не состояние, а историю, из которой состояние выводится. Взамен он даёт аудит, состояние на любую версию и пересобираемые модели чтения. Платой становятся отставание моделей чтения, конкурентность через ожидаемую версию с повтором команды, аккуратное чтение журнала проектором, снапшоты для длинных потоков и апкастеры для каждой смены схемы. Для простого CRUD это лишняя сложность, а для агрегата, история которого важнее итоговой строки, паттерн окупается.

 

Референсные ссылки