Crate es_entity 

A Rust library for persisting Event Sourced entities to PostgreSQL

This crate simplifies Event Sourcing persistence by automatically generating type-safe queries and operations for PostgreSQL. It decouples domain logic from persistence concerns while ensuring compile-time query verification via sqlx.

Documentation

• Book
• Github repository
• Cargo package

Features

• Store and construct from event sequences
• Type-safe and compile-time verification
• Simple and configurable query generation
• Easy idempotency checks
• Cursor-based pagination
• Flexible ID types
• Atomic operations

Modules

clock

Time abstraction for es-entity with support for real and manual time.

context

Thread-local system for adding context data to persisted events.

db

Centralized database type aliases.

error

Types for working with errors produced by es-entity.

events

Manage events and related operations for event-sourcing.

forgettable

Support for forgettable event data (e.g., for GDPR compliance).

hooks

Commit hooks for executing custom logic before and after transaction commits.

idempotent

Handle idempotency in event-sourced systems.

nested

Handle operations for nested entities.

one_time_executor

Type-safe wrapper to ensure one database operation per executor.

operation

Handle execution of database operations and transactions.

pagination

Control and customize the query execution and its response.

prelude

Convenience re-export of crates that the derive macros reference in generated code.

query

Query execution infrastructure for event-sourced entities.

snapshot

Core types for entity snapshotting.

sql_commenter

Correlate SQL statements with OpenTelemetry traces.

traits

Traits to orchestrate and maintain the event-sourcing pattern.

tree_query

Dynamically assembles the single-statement tree query a nested repo’s generated read fns execute at runtime: a tagged UNION ALL over one CTE per tree node, so a parent and all of its nested children (recursively) come back in one statement instead of one per level.

Macros

delegate_atomic_operation

Implements AtomicOperation for a type by delegating every method to an operation it holds.

entity_id

Create UUID-wrappers for database operations.

es_query

Execute an event-sourced query with automatic entity hydration.

idempotency_guard

Prevent duplicate event processing by checking for idempotent operations.

Structs

BisectOutcomes

The result of a completed search: one outcome per input item, plus what it cost.

BisectSearch

Drives a bisect over n items: which range to probe next, and what each verdict means for the ranges still outstanding.

ContextData

Immutable context data that can be safely shared across thread boundaries.

Continuation

A continuation to the next page, carrying the cursor it resumes from.

CursorDestructureError

DbOp

Default return type of the derived EsRepo::begin_op().

DbOpWithTime

Equivileant of DbOp just that the time is guaranteed to be cached.

EntityEvents

A Vec wrapper that manages event-stream of an entity with helpers for event-sourcing operations

EsQuery

Query builder for event-sourced entities.

EsQueryFlavorFlat

Query flavor for flat entities without nested relationships.

EsQueryFlavorNested

Query flavor for entities with nested relationships that need to be loaded recursively.

EventContext

Thread-local event context for tracking metadata throughout event sourcing operations.

EventContextFuture

A future wrapper that provides event context during polling.

EventWithContext

Forgettable

Wrapper for event fields containing data that can be forgotten (e.g., for GDPR).

ForgettableRef

A non-serializable reference to the value inside a Forgettable<T>.

ForgettableRemnants

Storage-level remnants of forgettable data found by a repository’s generated verify_forgotten check.

GenericEvent

Represent the events in raw deserialized format when loaded from database

HookSlot

Where a released SavepointOp’s staged commit hooks fold into.

HydrationRow

Internal common shape loaders normalise into before decoding a container.

Nested

NotFoundValue

Wrapper used by generated code to format not-found values. Prefers Display over Debug via inherent-vs-trait method resolution.

OneTimeExecutor

A struct that owns an sqlx::Executor.

OpWithTime

Wrapper that guarantees time is available, borrowing the underlying operation.

PaginatedQueryArgs

A cursor-based pagination structure for efficiently paginating through large datasets

PaginatedQueryRet

Return type for paginated queries containing entities and pagination metadata

PersistedEvent

Strongly-typed event wrapper with metadata for successfully stored events.

SavepointOp

An AtomicOperation scoped to a database SAVEPOINT inside a parent DbOp or another SavepointOp.

SnapshotGenericEvent

Row type of every loader on a snapshot repo (aliased as Repo__DbEvent there). GenericEvent<Id> itself is untouched — every existing repo’s query_as! and .sqlx entry stay as is; this confines the wider row shape to snapshot repos only.

SnapshotRecord

A persisted snapshot as loaded: the state plus the metadata of the events it summarises.

Sort

Structure to sort entities on a specific field when listing from database

TracingContext

TransientLimitExceeded

The transient allowance ran out: the same range kept failing on contention.

TransientPolicy

Which probe failures are transient, and how many re-probes they may buy.

TreeQuerySource

The root user query plus the bits needed to fold it into the tree query.

TreeSpec

Static description of one node (repo) in a nested tree, used to build the query.

Enums

BisectBudget

How many probes a bisect may spend before giving up on the ranges it has not yet resolved.

ConstraintKind

The kind of database constraint behind a classified ConstraintViolation.

EntityHydrationError

Error type for entity hydration failures (reconstructing entities from events).

Idempotent

Signals if a mutation is applied or was skipped.

ItemOutcome

One input item’s resolution. Positionally aligned with the input slice.

ListDirection

Controls the sorting order when listing the entities from the database

NoSnapshot

The default S of EntityEvents<E, S>: this entity has no snapshot.

Page

ProbeVerdict

What a probe over one range turned out to be.

Replay

One item of an entity’s replay. The snapshot, when present, is the FIRST item in forward order and the LAST item in reverse order. Deliberately exhaustive — do not add #[non_exhaustive].

Constants

DEFAULT_MAX_TRANSIENT_RETRIES

How many times a transiently-failed range may be re-probed before the search is abandoned.

NO_SNAPSHOT_FINGERPRINT

Matches no stored snapshot; binds on full-history loads and is NoSnapshot’s fingerprint.

Traits

AtomicOperation

Trait to signify we can make multiple consistent database roundtrips.

AtomicOperationWithTime

BatchIsolation

Batch isolation for every AtomicOperation.

CascadeDeleteNested

Trait for cascade soft-deleting child entities when a parent is deleted.

EsEntity

Required trait for all entities to be compatible and recognised by es-entity.

EsEvent

Required trait for all event enums to be compatible and recognised by es-entity.

EsRepo

Required trait for all repositories to be compatible with es-entity and generate functions.

EsSnapshot

Implemented by #[derive(EsSnapshot)] for user state types and by hand for NoSnapshot.

FromAlreadyApplied

Internal trait used by the idempotency_guard macro.

GuardWithoutSnapshotClause

Reached by idempotency_guard! when a stream yields Replay::Snapshot but the guard has no snapshot: clause. Only NoSnapshot (and SnapshotRecord<NoSnapshot>) implement it, so on a real snapshot this is a compile error with the message below.

HeadSnapshot

Implemented by every entity whose repo enables snapshot.

HydrateNested

IntoEvents

Required trait for converting new entities into their initial events before persistence.

IntoOneTimeExecutor

Marker trait for IntoOneTimeExecutorAt<'a> + 'a. Do not implement directly.

IntoOneTimeExecutorAt

A trait to signify that we can use an argument for 1 round trip to the database

IntoReplay

Normalises idempotency_guard! input: a plain &E stream (today’s call sites) and a replay() stream both become Replay. Do not implement for other types.

Parent

Trait that entities implement for every field marked #[es_entity(nested)]

RetryableInto

SavepointOperation

Savepoints for every AtomicOperation, derived rather than hand-written.

ToNotFoundValueFallback

TryFromEvents

Required trait for re-constructing entities from their events in chronological order.

WithEventContext

Extension trait for propagating event context across async boundaries.

Functions

build_tree_query

decode_tag

decode_tagged_row

Decodes a row from a tree branch with no snapshot columns (the branch’s own node has no snapshot table, and no sibling forced padding). Identical to what every tree branch decoded before snapshotting existed.

decode_tagged_snapshot_row

Decodes a row from a snapshot-enabled node’s own branch: event and recorded_at may be NULL (the lone snapshot-only row when the tail is empty), and the five snapshot* columns are present.

extract_constraint_value

Extracts the conflicting value from a database error’s constraint violation.

extract_events_pkey_id_value

Extracts the conflicting id from an events-table primary-key violation.

is_classified_constraint_violation

true when the database error is a violation kind the generated repo classifiers surface as ConstraintViolation: unique (SQLSTATE 23505), foreign key (23503), or check (23514). NOT NULL (23502) and exclusion (23P01) violations are not classified and surface as Sqlx.

is_retryable_conflict

retryable_conflict_code as a predicate.

parse_constraint_detail_value

Extracts the conflicting value from a PostgreSQL constraint violation detail message.

partition_by_tag

retryable_conflict_code

The Postgres sqlstate of a failure that says nothing about the statement that hit it, or None.

snapshot_fingerprints

Walks the tree in the same DFS order build_tree_query assigns fingerprint bind-parameter indices in (root, then children depth-first), returning the fingerprint of every node that has a snapshot table.

tree_has_snapshot

true if this node or any descendant enables snapshot. Determines whether every branch in the tree’s UNION ALL needs the same (wider) column list — a tree with no snapshot node anywhere emits the same SQL as before this feature existed.

Type Aliases

LastPersisted

An alias for iterator over the persisted events

Attribute Macros

es_event_context

Automatically captures function arguments into the event context.

retry_on_concurrent_modification

Retries the annotated async function when it fails with a concurrent modification error (or with any error when any_error = true).

Derive Macros

EsEntity

EsEvent

EsRepo

EsSnapshot