Skip to content

Latest commit

 

History

History
63 lines (42 loc) · 5.01 KB

events_and_streams.md

File metadata and controls

63 lines (42 loc) · 5.01 KB

The description of Event and Stream definitions

pg_eventstore provides classes to prepare the events to be inserted into the eventstore. The most important are:

  • PgEventstore::Event class which represents an event object
  • PgEventstore::Stream class which represents a stream object

Event object and its defaults

PgEventstore::Event has the following attributes:

  • id - String(UUIDv4, optional, not nil). If no provided - the value will be autogenerated.
  • type - String(optional, not nil). Default is an event's class name. Types which start from $ indicate system events. It is not recommended to prefix your events types with $ sign.
  • global_position - Integer(optional, read only). Event's global position in the eventstore, aka the "all" stream position (inspired by the popular EventstoreDB). Manually assigning this attribute has no effect. It is internally set when reading events from the database.
  • stream - PgEventstore::Stream(optional, read only). A Stream an event belongs to, see description below. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.
  • stream_revision - Integer(optional, read only). A revision of an event inside its stream.
  • data - Hash(optional). Event's payload data. For example, if you have a DescriptionChanged event class, then you may want to have a description value in the event payload data. Example: DescriptionChanged.new(data: { 'description' => 'Description of something', 'post_id' => SecureRandom.uuid })
  • metadata - Hash(optional). Event metadata. Event meta information which is not part of an events data payload. Example: { published_by: publishing_user.id }
  • link_id - String(UUIDv4, optional, read only). If an event is a link event (link events are pointers to other events), this attribute contains an id of the original event. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.
  • link_partition_id - Integer(optional, read only). If an event is a link event - this attribute contains a partition id of original event. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.
  • link - PgEventstore::Event(optional, read only). When reading from a stream using resolve_link_tos: true, if an event is resolved from a link - this attribute contains a PgEventstore::Event object which corresponds to that link. Manually assigning this attribute has no effect. It is internally set when reading events from the database.
  • created_at - Time(optional, read only). Database's timestamp when an event was appended to a stream. You may want to put your own timestamp into a metadata attribute - it may be useful when migrating between different databases. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.

Example:

PgEventstore::Event.new(data: { 'foo' => 'bar' }, type: 'FooChanged')

Stream object

To be able to manipulate a stream, you have to compute a stream's object first. It can be achieved by using the PgEventstore::Stream class. Here is a description of its attributes:

  • context - String(required). A Bounded Context, read more here. Values which start from $ sign are reserved by pg_eventstore. Such contexts can't be used to append events.
  • stream_name - String(required). A stream name.
  • stream_id - String(required). A stream id.

Example:

PgEventstore::Stream.new(context: 'Sales', stream_name: 'Customer', stream_id: '1')
PgEventstore::Stream.new(context: 'Sales', stream_name: 'Customer', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')

"all" stream

There is a special stream, called the "all" stream. You can get this object by calling the PgEventstore::Stream.all_stream method. Read more about the "all" stream in the Reading from the "all" stream section of Reading events chapter.

System streams

System stream is a special stream, the representation of which is pre-defined by the gem. System stream object can be created in next way:

PgEventstore::Stream.system_stream(stream_name)

Current list of system streams is:

  • "$streams". Reading from this stream will return 0 revision events. This allows effectively loop through a list of streams. Read more in Reading events chapter.

Important note

Because the database is designed for Eventsourcing, some limitations should be met - a combination of Event#type, Stream#context and Stream#stream_name must have low cardinality(low unique values number). This means you should pre-defined values there. Otherwise it may lead to the performance degradation. See How it works chapter for the details.