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

Link to this type expected_version() View Source
expected_version() ::
  :any_version |
  :no_stream |
  :stream_exists |
  non_neg_integer()
Link to this type start_from() View Source
start_from() :: :origin | :current | non_neg_integer()

Link to this section Functions

Link to this function ack(subscription, events) View Source
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.

Link to this function append_to_stream(stream_uuid, expected_version, events) View Source
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

Link to this function delete_snapshot(source_uuid) View Source
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

Link to this function read_all_streams_forward(start_event_id \\ 0, count \\ 1000) View Source
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.

Link to this function read_snapshot(source_uuid) View Source
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.

Link to this function read_stream_forward(stream_uuid, start_version \\ 0, count \\ 1000) View Source
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.

Link to this function record_snapshot(snapshot) View Source
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

Link to this function stream_all_forward(start_event_id \\ 0, read_batch_size \\ 1000) View Source
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.

Link to this function stream_forward(stream_uuid, start_version \\ 0, read_batch_size \\ 1000) View Source
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.

Link to this function subscribe_to_all_streams(subscription_name, subscriber, opts \\ []) View Source
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.

Link to this function subscribe_to_stream(stream_uuid, subscription_name, subscriber, opts \\ []) View Source
subscribe_to_stream(String.t(), String.t(), pid(), keyword()) ::
  {:ok, subscription :: pid()} |
  {:error, :subscription_already_exists} |
  {:error, reason :: term()}

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.

Link to this function unsubscribe_from_all_streams(subscription_name) View Source
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.

Link to this function unsubscribe_from_stream(stream_uuid, subscription_name) View Source
unsubscribe_from_stream(String.t(), String.t()) :: :ok

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.