PgEventstore

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

Requirements

• 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 recommend 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 which you will have to handle by yourself(e.g. by always wrapping your code using #multiple).
• pg_eventstore requires ruby v3+. The development of this gem is targeted at current ruby versions.

Installation

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

Usage

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
• Writing middlewares
• How to make multiple commands atomic

Admin web UI

pg_eventstore implements admin UI where you can browse various database objects. It is implemented as rack application. It doesn't have any authentication/authorization mechanism - it is your responsibility to take care of it.

Rails integration

In your config/routes.rb:

require 'pg_eventstore/web'

mount PgEventstore::Web::Application, at: '/eventstore'

Standalone application

Create config.ru file and place next content in there:

require 'pg_eventstore/web'

run PgEventstore::Web::Application

Now you can use any web server to run it.

Development

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

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.

Benchmarks

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

./benchmark/run

Publishing new version

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

Contributing

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.

License

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

Code of Conduct

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