This guide is designed for beginners who want to get started with a Sequent application from scratch. It does not assume that you have any prior experience with Sequent.

Sequent uses design patterns from DDD (Domain-Driven Design) like CQRS and Event Sourcing. Some basic familiarity with these principles is expected but you don’t need to be an expert. For more information on this we might refer to some DDD resources in the guide.

What is Sequent?

Sequent is a CQRS and Event Sourcing framework for Ruby. It enables you to capture all changes to an application state as a sequence of events, rather than just storing the current state. This has some advantages:

  • Time travel back to any prior state. i.e. for debugging.
  • Get auditability and traceability for free.
  • Backfill new tables/columns by replaying existing events.
  • Easy to reason about events with other stakeholders (Ubiquitous Language)

To read up on some of these concepts we recommend Martin Fowler’s wiki:

Basic flow

To illustrate the basic flow of a Sequent powered application, let’s use the example of creating a User in a web application:

  1. Webapp binds form elements to a CreateUser Command
  2. Webapp passes the Command to the CommandService
  3. The CommandService validates the Command
  4. When the Command is valid the CommandService calls the registered CommandHandlers
  5. The CommandHandler creates the User as an AggregateRoot and stores it in the EventStore using the AggregateRepository
  6. When the CommandHandler is finished, the CommandService queries all affected AggregateRoots for new Events and stores them in the EventStore
  7. All Events are propagated to registered Projectors
  8. The Projectors update their Projections by storing records in the database.

Good to know: Points 1,2,5,8 are the steps you as programmer need to implement. Sequent takes case of the rest.

Creating a new Sequent project

The best way to read this guide is to follow it step by step. All steps are essential to run this example application and no additional code or steps are needed.

By following along with this guide, you’ll create a Sequent project called blog, a (very) simple weblog. Before you can start building the application, you need to make sure that you have Sequent itself installed.

Installing Sequent

Before you install Sequent, you should check to make sure that your system has the proper prerequisites installed. These include Ruby and PostgreSQL.

Ruby

Verify that you have a current version of Ruby installed:

$ ruby -v
ruby 3.3.5 (2024-09-03 revision ef084cc8f4) [arm64-darwin23]

Sequent requires Ruby version 3.2.0 or later. If the version number returned is lower, you’ll need to upgrade your Ruby version. For managing Ruby versions we recommend rbenv.

Postgres

You will also need to have the PostgreSQL database server installed. Verify that you have a current version of PostgresQL installed:

$ pg_config --version
PostgreSQL 16.3

Sequent works with PostgreSQL version 14.x or later, but we recommend you install the lastest version. For installation instructions refer to your OS or see postgresql.org.

Sequent

Install Sequent using RubyGems:

$ gem install sequent

Verify that Sequent was installed correctly by running the command:

$ sequent
Please specify a command. i.e. `sequent new myapp`

Creating the Blog application

Sequent offers generators to help you develop your application without having to set up the plumbing of the system yourself. We can generate a new Sequent application using sequent:

$ sequent new blog

Success!

...

This will create your new Sequent application in the blog directory and guide you toward your next steps. Don’t rush in yet, we will follow these steps in a minute. Let’s switch to the blog application folder:

$ cd blog

We can see the blog directory was generated with a number of files and folders that form the basic structure of a Sequent application:

$ ls -1
Gemfile
Gemfile.lock
Rakefile
app
blog.rb
config
db
lib
spec

Now let’s finish our setup by installing the gems and preparing the database:

bundle install
bundle exec rake sequent:db:create
SEQUENT_ENV=test bundle exec rake sequent:db:create
bundle exec rake sequent:db:create_view_schema
bundle exec rake sequent:migrate:online
bundle exec rake sequent:migrate:offline

If your database already exists and you just need to create the event_store schema and the view_schema then do:

bundle exec rake sequent:db:create_event_store
bundle exec rake sequent:db:create_view_schema
bundle exec rake sequent:migrate:online
bundle exec rake sequent:migrate:offline

Your Sequent app is ready to rock!

Hello, Sequent!

Sequent does not come with a web framework included. We’ll look into bringing it all together in a later guide. As such, a real “hello world” is outside the scope of this guide. What we can do is demonstrate our business logic is working. We’ll examine our example domain in a minute. Let’s first take a look at our (generated) specs:

  • spec/lib/post/post_command_handler_spec.rb: Here we test that when a command is given, certain events will occur.
  • spec/app/projectors/post_projector_spec.rb: Here we test that when an event occurs, the projector updates the view records.

Now we run the specs to ensure we have a working system:

$ bundle exec rspec
...

Finished in 0.2 seconds (files took 1.4 seconds to load)
3 examples, 0 failures

The specs are green and we are ready to dive into the domain! Let’s continue with: 1.2 Modelling the domain