EventStore

A Ruby implementation of an EventStore based on Active Record.

Installation

• Add following line to your application's Gemfile:

gem 'rails_event_store'

• Use provided task to generate a table to store events in you DB.

rails generate rails_event_store:migrate
rake db:migrate

Usage

To communicate with ES you have to create instance of RailsEventStore::Client class.

client = RailsEventStore::Client.new

Creating new event

Firstly you have to define own event model extending RailsEventStore::Event class.

class OrderCreated < RailsEventStore::Event
end

stream_name = "order_1"
event_data = {
               data: { data: "sample" },
               event_id: "b2d506fd-409d-4ec7-b02f-c6d2295c7edd"
             }
event = OrderCreated.new(event_data)

#publishing event for specific stream
client.publish_event(event, stream_name)

#publishing global event. In this case stream_name is 'all'.
client.publish_event(event)

Creating new event with optimistic locking:

class OrderCreated < RailsEventStore::Event
end

stream_name = "order_1"
event_data = {
               data: { data: "sample" },
               event_id: "b2d506fd-409d-4ec7-b02f-c6d2295c7edd"
             }
event = OrderCreated.new(event_data)
expected_version = "850c347f-423a-4158-a5ce-b885396c5b73" #last event_id
client.publish_event(event, stream_name, expected_version)

Reading stream's events forward in batch

stream_name = "order_1"
start = "850c347f-423a-4158-a5ce-b885396c5b73"
count = 40
client.read_all_events(stream_name, start, count)

Reading all events from stream forward

This method allows us to load all stream's events ascending.

stream_name = "order_1"
client.read_all_events(stream_name)

Reading all events forward

This method allows us to load all stored events ascending.

client.read_all_streams

Deleting stream

You can permanently delete all events from a specific stream. Use this wisely.

stream_name = "product_1"
client.delete_stream(stream_name)

Subscribing to events

To listen on specific events synchronously you have to create subscriber reprezentation. The only requirement is that subscriber class has to implement the 'handle_event(event)' method.

class InvoiceReadModel
  def handle_event(event)
    #we deal here with event's data
  end
end

• You can subscribe on specific set of events

invoice = InvoiceReadModel.new
client.subscribe(invoice, ['PriceChanged', 'ProductAdded'])

• You can also listen on all incoming events

invoice = InvoiceReadModel.new
client.subscribe_to_all_events(invoice)

Building an event sourced application with RailsEventStore gem

ArrgegateRoot module & AggregateReporitory have been extracted from RailsEventStore to separate gem. See aggregate_root gem readme to find help how to start. Also this example might be useful.

Resources

There're already few blogposts about Rails EventStore. Check them out:

• Why use Event Sourcing
• The Event Store for Rails developers
• Fast introduction to Event Sourcing for Ruby programmers
• Why I want to introduce mutation testing to the rails_event_store gem

About

Rails Event Store is funded and maintained by Arkency. Check out our other open-source projects.

You can also hire us or read our blog.