# Sequent: CQRS and event sourcing in Ruby, and the workflow around it

> Sequent is a Ruby framework for command query responsibility segregation and event sourcing, and the README is short because the real content lives elsewhere: an official documentation site, a Jekyll docs directory, a spec suite that needs PostgreSQL, a multi-version gemfile set for ActiveRecord, and a release process run through rake. The framework is MIT licensed and actively worked on.

**zilverline/sequent** — CQRS & event sourcing framework for Ruby

- Repository: https://github.com/zilverline/sequent
- Website: https://sequent.io
- Stars: 562 · Forks: 60
- Language: Ruby
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/zilverline-sequent

## The framework is one line and the documentation is the product

Sequent is described in a single quoted line as a CQRS and event sourcing framework written in Ruby, and the README immediately hands you to the official site at sequent.io for anything more. That is a deliberate arrangement rather than a thin document, because a CQRS and event sourcing framework has a lot of concept to explain before you write your first command. The README covers three things properly: how to get started, how to work on the project itself, and how to release it, and it points at a Getting Started page for people new to the framework. The project topics list ActiveRecord alongside cqrs, eventsourcing and eventstore, so the persistence story is built on ActiveRecord rather than on a bespoke storage layer, which is a meaningful choice for a Ruby framework, since it means the event store is a table in the database you already run. The repository carries a CHANGELOG.md and the README says the most notable changes can be found there, and there is a CHANGELOG in the tree at the top level. The licence is MIT, and the repository is not archived, with the last push on 2026-10-20, so the work is current even though the project has no GitHub releases.

## A development environment you can start with one command

The contributing section is the most concrete part of the README, and it describes a setup that is unusually well tooled for a Ruby project. You can set up a working development environment manually, or you can use devenv.sh with Nix, and you can also use direnv to set up your environment automatically, with a .envrc.example file holding the minimal configuration. Then the workflow is two commands, with devenv up to start Postgres and Jekyll, and devenv test to recreate the databases and run the specs. The choice of tools says something about the project. A database and a documentation site are both required to work on Sequent, and devenv with Nix gives you both pinned, which removes the class of problem where a contributor's local Postgres version differs from the project's and the specs fail for reasons that have nothing to do with the change. The direnv route is the lighter version of the same idea, and the presence of a flake.lock and a flake.nix at the top of the repository means the Nix setup is itself pinned. The tree also holds a .ruby-version file, which pins the Ruby the project expects, and a .rubocop.yml, so the style rules are in the repository rather than in a wiki page.

## The specs need a real PostgreSQL, and there are two ways to get one

The running the specs section explains the database setup, and the two options are the standard ones. When using a local PostgreSQL database you create the user yourself.

```bash
  createuser -D -s -R sequent
```

If you are not using a local Postgres database, the README gives a Docker command that starts one for you.

```bash
  docker run --name sequent -e POSTGRES_HOST_AUTH_METHOD=trust -e POSTGRES_USER=sequent -p 5432:5432 -d postgres:16
```

Two details in that command are worth noting. The trust authentication method is used so the container starts without a password, which is fine for a throwaway test database and is why the port is published on the standard Postgres port. And the image is pinned to a specific major version, postgres:16, which keeps the database behaviour consistent across contributors. After that, Sequent creates its own database through a rake task.

```bash
SEQUENT_ENV=test bundle exec rake sequent:db:create
```

You then run rspec spec to run the tests with the current database schema, and the README explains the difference between that and the fuller invocation.

```bash
SEQUENT_ENV=test rake sequent:db:drop sequent:db:create spec
```

The second form drops and recreates the database first, which ensures the specs run against the latest schema. The SEQUENT_ENV=test variable appears in both, so the environment is selected explicitly rather than inferred, and the repository holds both a spec/ directory and an integration-specs/ directory, which suggests the suite is split into unit level specs and slower integration specs that talk to a real database.

## The documentation is a Jekyll site, and it is edited in the same repository

The documentation section explains that the official site is at sequent.io, and it invites two kinds of contribution, an issue if you want to help improve the documentation, and a pull request if you want to help write it. The site itself is built from the docs/ directory in this repository, with Jekyll, and you can start it locally with four commands.

```bash
cd docs
bundle install
cp .env.example .env
bundle exec jekyll serve --livereload
```

Then you open localhost:4000. The livereload flag matters for a documentation workflow, since it means a change to a page is visible in the browser without a manual refresh, and the .env file is how the site is configured, copied from the .env.example template. There is one dependency to be aware of, that a GitHub personal access token is required if you want Jekyll to retrieve GitHub metadata information, and the README notes that no scope is required for the token, which is a small sign of care in the setup. The docs directory in the tree also holds a _config.yml, and the top level of the repository has its own .envrc.example for the direnv workflow, so the two environment setups are kept separate rather than sharing one file. Keeping the documentation source next to the code it describes is a deliberate choice, and it means a change to the framework and a change to the guide about it can be in the same pull request.

## Releasing means editing one file and updating every gemfile

The release section is short and procedural, and it says more about the project than any marketing copy would. You ensure the version in lib/version.rb is the new version, and if not, change it, and then update the sequent version for all the gemfiles.

```bash
BUNDLE_GEMFILE=gemfiles/ar_7_2.gemfile bundle update sequent --conservative
BUNDLE_GEMFILE=gemfiles/ar_8_0.gemfile bundle update sequent --conservative
```

The naming of those gemfiles, ar_7_2 and ar_8_0, tells you what the multi-version support is for, since they correspond to ActiveRecord 7.2 and 8.0, and the conservative flag on the bundle update means the update pulls in as little churn as possible. The gemfiles/ directory in the tree holds one gemfile per supported ActiveRecord version, which is how a gem can support a range of framework versions without forcing a choice on the user. After committing the changes you run rake release, and the README states what that does, that a git tag will be created and pushed, and the new version of the gem will be pushed to rubygems. So the release path is a single rake task that handles the tag and the push to RubyGems, which is the sort of automation that makes a maintainer willing to release often. The version file, the per-version gemfiles and the rake task together are the operational core of the project, and they are also the clearest statement of what Sequent expects from the applications that use it.

## Where Sequent is the wrong choice

The first limit is conceptual and it comes before any technical detail. CQRS and event sourcing is a substantial architectural commitment, with a write model that produces events, a read model that is built from those events, and a set of consistency questions that follow from the gap between the two. The README does not try to talk anyone into that trade, it just points at the manifesto-style documentation and the Getting Started page, and for a project whose domain does not benefit from an immutable history of every change, the extra machinery is a cost with no return. The second is the operational shape. The specs need PostgreSQL, the development environment wants Nix or direnv, and the documentation wants a Jekyll build, so contributing is heavier than it would be for a gem with a thin test suite, and that friction affects how many people will send you patches. The third is the release and version story. There are no GitHub releases, so a version history has to be read out of the changelog and the tags, and the ActiveRecord version matrix means your dependency resolution is wider than a single gemfile would give you. The fourth is that the README itself is thin, and every real question about the API is answered on a website rather than in the repository, which is fine for users and awkward for anyone who wants to search, quote or archive the guidance. The repository does ship a .rubocop.yml, a .ruby-version, a Rakefile and a sequent.gemspec, so the packaging is conventional and inspectable, but the design work is where the depth is, and that lives outside the tree.

## Conclusion

Adopt Sequent if you are building a Ruby system where the write model and read model genuinely differ and you want a framework that already encodes that separation rather than a set of conventions. Skip it if your domain does not need an event stream, since the complexity is only worth it where the history is part of the product. Verify first which ActiveRecord version your app uses and that the matching gemfile exists, that your PostgreSQL setup can create the sequent role and database, and that the current API in the documentation site matches the version of the gem you pin.

## FAQ

### What is Sequent and where is its documentation?

Sequent is a CQRS and event sourcing framework written in Ruby, with ActiveRecord listed among the project topics. The README is brief and points to the official site at sequent.io, with a Getting Started page for newcomers, and the site source lives in the docs/ directory of the repository as a Jekyll site.

### How do I run the Sequent specs?

You need PostgreSQL, either a local one where you create the user with createuser -D -s -R sequent, or a container started with the documented docker run command using postgres:16. Then run SEQUENT_ENV=test bundle exec rake sequent:db:create and rspec spec, or use the fuller SEQUENT_ENV=test rake sequent:db:drop sequent:db:create spec to rebuild the schema first.

### How is a new version of Sequent released?

You set the version in lib/version.rb, update the sequent version across all the gemfiles with bundle update sequent --conservative for each supported ActiveRecord version, commit, and then run rake release, which creates and pushes a git tag and pushes the new version of the gem to rubygems.

## Sources

- [Issues](https://github.com/zilverline/sequent/issues)
- [License: MIT](https://github.com/zilverline/sequent/blob/master/LICENSE)
- [Project website](https://sequent.io)
- [README](https://github.com/zilverline/sequent/blob/master/README.md)
- [zilverline/sequent on GitHub](https://github.com/zilverline/sequent)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zilverline-sequent