PgEventstore

Implements database and API to store and read events in event sourced systems.

• pg_eventstore requires a PostgreSQL database with jsonb data type support (which means you need to have v9.2+). However it is recommended to use a non EOL PostgreSQL version, because the development of this gem is targeted at current PostgreSQL versions.
• It is recommended you to have the default value set for default_transaction_isolation PostgreSQL config setting("read committed") as the implementation relies on it. All other transaction isolation levels("repeatable read" and "serializable") may cause unexpected serialization errors.
• It is recommended to use a connection pooler (for example PgBouncer) in transaction pool mode to lower the load on a database.
• pg_eventstore requires ruby v3+. The development of this gem is targeted at current ruby versions.

Install the gem and add to the application's Gemfile by executing:

$ bundle add pg_eventstore

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install pg_eventstore

Before start using the gem - you have to create the database. Please include this line into your Rakefile:

load "pg_eventstore/tasks/setup.rake"

This will include necessary rake tasks. You can now run

# Replace this with your real connection url
export PG_EVENTSTORE_URI="postgresql://postgres:postgres@localhost:5532/eventstore"
bundle exec rake pg_eventstore:create
bundle exec rake pg_eventstore:migrate

to create the database, necessary database objects and migrate them to the latest version. After this step your pg_eventstore is ready to use. There is also a rake pg_eventstore:drop task which drops the database.

Documentation chapters:

• Configuration
• Events and streams definitions
• Appending events
• Linking events
• Reading events
• Subscriptions
• Maintenance functions
• Writing middlewares
• How to make multiple commands atomic
• Admin UI

The gem is shipped with its own CLI. Use pg-eventstore --help to find out its capabilities.

The gem provides a class to clean up your pg_eventstore test db between tests. Example usage(in your spec/spec_helper.rb:

require 'pg_eventstore/rspec/test_helpers'

RSpec.configure do |config|
  config.before do
    PgEventstore::TestHelpers.clean_up_db
  end
end

If you would like to be able to test the functional, provided by PgEventstore::Extensions::OptionsExtension extension - there is a rspec matcher. Load custom matcher in you spec_helper.rb:

require 'pg_eventstore/rspec/has_option_matcher'

Let's say you have next class:

class SomeClass
  include PgEventstore::Extensions::OptionsExtension

  option(:some_opt, metadata: { foo: :bar }) { '1' }
end

To test that its instance has the proper option with the proper default value and proper metadata you can use this matcher:

RSpec.describe SomeClass do
  subject { described_class.new }

  # Check that :some_opt is present
  it { is_expected.to have_option(:some_opt) }
  # Check that :some_opt is present and has the correct default value
  it { is_expected.to have_option(:some_opt).with_default_value('1').with_metadata(foo: :bar) }
end

After checking out the repo, run:

• bundle to install dependencies
• docker compose up to start dev/test services
• bin/setup_db to create/re-create development and test databases, tables and related objects
• bundle exec rbs collection install to install external rbs definitions

Then, run bin/rspec 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 run admin UI web server - run puma in your terminal. By default it will start web server on http://0.0.0.0:9292.

There is a script to help you to tests the pg_eventstore implementation performance. You can run it using next command:

./benchmark/run

1. Push commit with updated version.rb file to the release branch. The new version will be automatically pushed to rubygems.
2. Create release on GitHub.
3. Update CHANGELOG.md

Bug reports and pull requests are welcome on GitHub at https://github.com/yousty/pg_eventstore. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

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

Everyone interacting in the PgEventstore project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.