Installation

Quick setup

New Rails application

If you're setting up a new Rails app, there is a fast way to begin with RailsEventStore using template.

The template will:

• add rails_event_store to your Gemfile
• generate config/initializers/rails_event_store.rb with sane defaults and expose client under Rails.configuration.event_store
• pre–configure event browser to make it available under /res url in your app
• run bundler to install necessary dependencies
• generate migrations files and run them

rails new -m https://railseventstore.org/new APP_NAME

Loading asciinema cast...

Obviously, you can specify all the options which rails new takes, e.g. database you want to use:

rails new -m https://railseventstore.org/new APP_NAME --database=postgresql

Existing Rails application

The easiest way to install RailsEventStore and don't scratch your head is to use the template.

Simply cd to your Rails application root directory and run:

bin/rails app:template LOCATION=https://railseventstore.org/new

Loading asciinema cast...

The template will:

• add rails_event_store to your Gemfile
• generate config/initializers/rails_event_store.rb with sane defaults and expose client under Rails.configuration.event_store
• pre–configure event browser to make it available under /res url in your app
• run bundler to install necessary dependencies
• generate migrations files and run them (respecting your database setup)

Advanced setup

Steps described below are not required if you went with quick setup.

Installation with Bundler

If your application dependencies happen to be managed by Bundler, please add the following line to your Gemfile:

gem "rails_event_store"

After running bundle install, Rails Event Store should be ready to be used.

Installation using RubyGems

You can also install this library using the gem command:

gem install rails_event_store

After requiring rubygems in your project you should be ready to use Rails Event Store.

Setup data model

Use provided task to generate a table to store events in your database. If you use spring, stop it first via spring stop.

Sqlite

bin/rails generate ruby_event_store:active_record:migration
bin/rails db:migrate

MySQL

bin/rails generate ruby_event_store:active_record:migration
bin/rails db:migrate

PostgreSQL

We find jsonb as the most reasonable data type for storing events. It is available since PostgreSQL 9.4.

bin/rails generate ruby_event_store:active_record:migration --data-type=jsonb
bin/rails db:migrate

Instantiate a client

# config/environments/*.rb

Rails.application.configure do
  config.to_prepare do
    Rails.configuration.event_store = RailsEventStore::Client.new
    # add subscribers here
  end
end

or

# config/application.rb
module YourAppName
  class Application < Rails::Application
    config.to_prepare do
      Rails.configuration.event_store = RailsEventStore::Client.new
      # add subscribers here
    end
  end
end

or

# config/initializers/rails_event_store.rb
Rails.configuration.to_prepare do
  Rails.configuration.event_store = RailsEventStore::Client.new
  # add subscribers here
end

Then in your application code you can reference it as:

Rails.configuration.event_store

In Rails development mode when you change a registered class, it is reloaded, and a new class with same name is constructed. To keep RailsEventStore aware of changes in event classes, handler classes, and handler subscriptions use to_prepare callback. It is executed before every code reload in development, and once in production.

Client for jsonb data type

If you decided to use jsonb data type for storing events, you can use a client that is optimized for this data type:

Rails.configuration.event_store = RailsEventStore::JSONClient.new

It provides the same features and API as the default client, but it is optimized for jsonb data type, providing valid configuration for serialization and deserialization of events.