EventStore v0.12.0 EventStore View Source
EventStore is CQRS event store implemented in Elixir.
It uses PostgreSQL (v9.5 or later) as the underlying storage engine.
The EventStore
module provides the public API to read and write events to an event stream, and subscribe to event notifications.
Please check the getting started and usage guides to learn more.
Example usage
# append events to a stream
:ok = EventStore.append_to_stream(stream_uuid, expected_version, events)
# read all events from a stream, starting at the beginning
{:ok, recorded_events} = EventStore.read_stream_forward(stream_uuid)
Link to this section Summary
Functions
Acknowledge receipt of the given events received from a single stream, or all streams, subscription
Append one or more events to a stream atomically
Get the event store configuration for the environment
Get the serializer configured for the environment
Delete a previously recorded snapshop for a given source
Reads the requested number of events from all streams, in the order in which they were originally written
Read a snapshot, if available, for a given source
Reads the requested number of events from the given stream, in the order in which they were originally written
Record a snapshot of the data and metadata for a given source
Streams events from all streams, in the order in which they were originally written
Streams events from the given stream, in the order in which they were originally written
Subscriber will be notified of every event persisted to any stream
Subscriber will be notified of each batch of events persisted to a single stream
Unsubscribe an existing subscriber from all event notifications
Unsubscribe an existing subscriber from event notifications
Link to this section Types
expected_version() :: :any_version | :no_stream | :stream_exists | non_neg_integer()
Link to this section Functions
ack(pid(), EventStore.RecordedEvent.t() | [EventStore.RecordedEvent.t()] | non_neg_integer()) :: :ok | {:error, reason :: term()}
Acknowledge receipt of the given events received from a single stream, or all streams, subscription.
append_to_stream(String.t(), expected_version(), [EventStore.EventData.t()]) :: :ok | {:error, :wrong_expected_version} | {:error, :stream_exists} | {:error, :stream_does_not_exist} | {:error, reason :: term()}
Append one or more events to a stream atomically.
stream_uuid
is used to uniquely identify a stream.expected_version
is used for optimistic concurrency checks. You can provide a non-negative integer to specify the expected stream version. This is used to ensure you can only append to the stream if it is at exactly that version.You can also provide one of the following values to affect the concurrency check behaviour:
:any_version
- No concurrency checking; allow any stream version (including no stream).:no_stream
- Ensure the stream does not exist.:stream_exists
- Ensure the stream exists.
events
is a list of%EventStore.EventData{}
structs.
Returns :ok
on success, or an {:error, reason}
tagged tuple. The returned
error may be due to one of the following reasons:
{:error, :wrong_expected_version}
when the actual stream version differs from the provided expected version.{:error, :stream_exists}
when the stream exists, but expected version was:no_stream
.{:error, :stream_does_not_exist}
when the stream does not exist, but expected version was:stream_exists
.
Get the event store configuration for the environment
Get the serializer configured for the environment
delete_snapshot(String.t()) :: :ok | {:error, reason :: term()}
Delete a previously recorded snapshop for a given source
Returns :ok
on success, or when the snapshot does not exist
read_all_streams_forward(non_neg_integer(), non_neg_integer()) :: {:ok, [EventStore.RecordedEvent.t()]} | {:error, reason :: term()}
Reads the requested number of events from all streams, in the order in which they were originally written.
start_event_id
optionally, the id of the first event to read. Defaults to the beginning of the stream if not set.count
optionally, the maximum number of events to read. If not set it will be limited to returning 1,000 events from all streams.
read_snapshot(String.t()) :: {:ok, EventStore.Snapshots.SnapshotData.t()} | {:error, :snapshot_not_found}
Read a snapshot, if available, for a given source.
Returns {:ok, %EventStore.Snapshots.SnapshotData{}}
on success, or {:error, :snapshot_not_found}
when unavailable.
read_stream_forward(String.t(), non_neg_integer(), non_neg_integer()) :: {:ok, [EventStore.RecordedEvent.t()]} | {:error, reason :: term()}
Reads the requested number of events from the given stream, in the order in which they were originally written.
stream_uuid
is used to uniquely identify a stream.start_version
optionally, the version number of the first event to read. Defaults to the beginning of the stream if not set.count
optionally, the maximum number of events to read. If not set it will be limited to returning 1,000 events from the stream.
record_snapshot(EventStore.Snapshots.SnapshotData.t()) :: :ok | {:error, reason :: term()}
Record a snapshot of the data and metadata for a given source
Returns :ok
on success
stream_all_forward(non_neg_integer(), non_neg_integer()) :: Enumerable.t()
Streams events from all streams, in the order in which they were originally written.
start_event_id
optionally, the id of the first event to read. Defaults to the beginning of the stream if not set.read_batch_size
optionally, the number of events to read at a time from storage. Defaults to reading 1,000 events per batch.
stream_forward(String.t(), non_neg_integer(), non_neg_integer()) :: Enumerable.t() | {:error, reason :: term()}
Streams events from the given stream, in the order in which they were originally written.
start_version
optionally, the version number of the first event to read. Defaults to the beginning of the stream if not set.read_batch_size
optionally, the number of events to read at a time from storage. Defaults to reading 1,000 events per batch.
subscribe_to_all_streams(String.t(), pid(), keyword()) :: {:ok, subscription :: pid()} | {:error, :subscription_already_exists} | {:error, reason :: term()}
Subscriber will be notified of every event persisted to any stream.
subscription_name
is used to uniquely identify the subscription.subscriber
is a process that will be sent{:events, events}
notification messages.opts
is an optional map providing additional subscription configuration:start_from
is a pointer to the first event to receive. It must be one of::origin
for all events from the start of the stream (default).:current
for any new events appended to the stream after the subscription has been created.- any positive integer for an event id to receive events after that exact event.
mapper
to define a function to map each recorded event before sending to the subscriber.
Returns {:ok, subscription}
when subscription succeeds.
Subscriber will be notified of each batch of events persisted to a single stream.
stream_uuid
is the stream to subscribe to. Use the$all
identifier to subscribe to events from all streams.subscription_name
is used to uniquely identify the subscription.subscriber
is a process that will be sent{:events, events}
notification messages.opts
is an optional map providing additional subscription configuration:start_from
is a pointer to the first event to receive. It must be one of::origin
for all events from the start of the stream (default).:current
for any new events appended to the stream after the subscription has been created.- any positive integer for a stream version to receive events after.
mapper
to define a function to map each recorded event before sending to the subscriber.
Returns {:ok, subscription}
when subscription succeeds.
unsubscribe_from_all_streams(String.t()) :: :ok
Unsubscribe an existing subscriber from all event notifications.
subscription_name
is used to identify the existing subscription to remove.
Returns :ok
on success.
Unsubscribe an existing subscriber from event notifications.
stream_uuid
is the stream to unsubscribe from.subscription_name
is used to identify the existing subscription to remove.
Returns :ok
on success.