EventSourcery::Postgres

A PostgreSQL event store and projections adapter for EventSourcery.

Development Status

EventSourcery::Postgres is in production use at Envato.

Requirements

• Ruby >= 2.6.0
• PostgreSQL

The event store relies on the uuid-ossp PostgreSQL extension (enabled automatically by EventSourcery::Postgres::Schema.create_events) and the Sequel pg_json extension (loaded automatically when you assign a database connection in the configuration).

Installation

Add this line to your application's Gemfile:

gem 'event_sourcery-postgres'

Configure

EventSourcery::Postgres.configure do |config|
  config.event_store_database = Sequel.connect(...)
  config.projections_database = Sequel.connect(...)
  config.write_events_function_name = 'writeEvents'
  config.events_table_name = :events
  config.aggregates_table_name = :aggregates
  config.callback_interval_if_no_new_events = 60
end

Database setup

Before events can be stored or projected the required tables and database functions need to be created. Once the databases are configured (see above), create the event store schema:

# Creates the events table, the aggregates table, and the `writeEvents`
# database function on the event store database.
EventSourcery::Postgres::Schema.create_event_store

Projectors and reactors track their progress in a tracker table. By default this table is created automatically the first time a processor runs (via the auto_create_projector_tracker config option). To create it explicitly instead:

EventSourcery::Postgres::Schema.create_projector_tracker

Each of these methods accepts keyword arguments (db:, events_table_name:, etc.) if you need to override the defaults taken from the configuration.

Usage

Event Store

ItemAdded = EventSourcery::Event

EventSourcery::Postgres.config.event_store.sink(ItemAdded.new(aggregate_id: uuid, body: {}))
EventSourcery::Postgres.config.event_store.get_next_from(0).each do |event|
  puts event.inspect
end

Projectors & Reactors

class ItemProjector
  include EventSourcery::Postgres::Projector

  table :items do
    column :item_uuid, 'UUID NOT NULL'
    column :title, 'VARCHAR(255) NOT NULL'
  end

  project ItemAdded do |event|
    table(:items).insert(item_uuid: event.aggregate_id,
                         title: event.body.fetch('title'))
  end
end

class UserEmailer
  include EventSourcery::Postgres::Reactor

  emits_events SignUpEmailSent

  process UserSignedUp do |event|
    emit_event SignUpEmailSent.new(user_id: event.aggregate_id) do
      UserMailer.signed_up(...).deliver
    end
  end
end

EventSourcery::EventProcessing::ESPRunner.new(
  event_processors: [item_projector, user_emailer],
  event_store:      EventSourcery::Postgres.config.event_store,
  stop_on_failure:  true,
).start!

Development

After checking out the repo, run bin/setup to install dependencies. (This will install dependencies and recreate the test database.) Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

To release a new version:

1. Update the version number in lib/event_sourcery/postgres/version.rb
2. Get this change onto main via the normal PR process
3. Run bundle exec rake release, this will create a git tag for the version, push tags up to GitHub, and upload the gem to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/envato/event_sourcery-postgres.

License

The gem is available as open source under the terms of the MIT License.