Important: Please take note for the current known limitations when working with Projectors and Record classes.

Projectors are responsible for creating projections based on events. Projections are records in tables. Sequent uses ActiveRecord for CRUD-ing records in the database. Sequent uses the term Records to describe the Projections. In Sequent, Projectors inherit from Sequent::Projector. To store something in a Projection you need 3 things in Sequent:

  1. A Projector. Responsible for creating Projections. We are discussing Projectors in this chapter.
  2. A Record class. This is a Sequent::ApplicationRecord class, subclassing ActiveRecord::Base. In Sequent, Records can only be updated/created/deleted inside Projectors. The rest of the application needs to regard these objects as read-only. Sequent enforces this for Record classes that include Sequent::Core::ProjectionRecord, see Read-only records.
  3. An SQL file. The SQL contains the table definition in which the Record will be stored. Please check out the chapter on Migrations for an in-depth description on how migrations work in Sequent.

The nature of view state in event sourced applications is not compatible with the ActiveRecord migration model, therefore it is not used. In event sourced applications the view state is always derived from Events. When you want to have another view state (maybe you add a column, or group some attributes), you replay the affected Projectors.

In Sequent a Projector is defined as follows:

class UserProjector < Sequent::Projector
  manages_tables UserRecord
end

Sequent::Projector exposes the manages_tables method in which you state which Records this Projector manages. There are two important things you need to know:

  1. A Record can only be managed by one Projector. A Projector can however manage multiple Records.
  2. A Projector should only access Records it manages.

A Projector is used in two different stages in your application.

  1. During normal operation. This is when your application is running and Events are coming in. The Projector updates the Records as you specified.
  2. During migrations. During a migration some Projectors are rebuilt in the background to build up new projections. Because of this, a Projector can only access Records it manages, since another Projector might not be finished rebuilding. In Sequent we replay on a per aggregate basis.

If you didn’t set enable_autoregistration to true you will need to add your Projectors manually to your Sequent configuration in order to use them.

  Sequent.configure do |config|
    config.event_handlers = [
      UserProjector.new
    ]
  end

Creating a Record

To create a Record in Sequent, you add a code block that listens to the appropriate Event and creates a Record in the database.

class UserProjector < Sequent::Projector
  on UserCreated do |event|
    create_record(UserRecord, {aggregate_id: event.aggregate_id, created_at: event.created_at})
  end
end

A Record whose table has a created_at column must be created with a created_at, usually the created_at of the Event, otherwise creating it fails with a Sequent::Core::Persistors::MissingCreatedAtError. Its updated_at is the same unless it is given. The persistors would otherwise use the current time, so the Record would get other timestamps when the Events are replayed. A block given to create_record can also set it.

Internally a Projector uses a Sequent::Core::Persistors::Persistor to access the database. During normal operations this is the ActiveRecordPersistor. This means the above code is eventually translated to:

user_record = UserRecord.new(aggregate_id: event.aggregate_id, created_at: event.created_at)
user_record.save!

Sequent::Projector provides a set of methods to create/read/update/delete Records as wrapper around ActiveRecord. The reason for the extra abstraction is performance during migration of Projectors. During a migration, a highly optimized Persistor - the ReplayOptimizedPostgresPersistor - is used to speed up bulk inserting. Because of the abstraction, you need to use the provided wrapper methods. This poses some restrictions on how you can use ActiveRecord functionality. For instance you can not add child relations via the parent, as you might be used to in a “normal” ActiveRecord application.

parent = ParentRecord.new
parent << ChildRecord.new
parent.save!

In Sequent this will not work. You need to persist child records the same as you would persist the parent record.

class UserProjector < Sequent::Projector
  on ParentCreated do |event|
    create_record(ParentRecord, {aggregate_id: event.aggregate_id, created_at: event.created_at})
    event.children.each do |child|
      create_record(
        ChildRecord,
        {parent_record_id: event.aggregate_id, child_id: child.child_id, created_at: event.created_at},
      )
    end
  end
end

Updating a record

To update a Record in Sequent, use the update_all_records method. This method has 3 parameters:

  • the Record class
  • the where clause as a Hash (generally using the aggregate_id attribute)
  • the updates as a Hash
class UserProjector < Sequent::Projector
  on UserNameSet do |event|
    update_all_records(
      UserRecord,
      event.attributes.slice(:aggregate_id), # the where clause as a hash
      event.attributes.slice(:firstname, :lastname) # the updates as a hash
    )
  end
end

Tip: You can access all attrs from an Event via the attributes method. This returns a Hash on which you can call slice, which in turn returns a Hash containing the key value pairs of the keys you requested. This is extra handy if the key names in the attrs are the same as the column names in your table definition.

A Record updated using a block (with update_record, do_with_record, do_with_records or create_or_update_record) only gets a new updated_at when it is set: update_record sets it to the time of the Event, and other blocks have to set it themselves. So the projected updated_at does not depend on when the Events are handled, and is the same after a replay.

Deleting a record

To delete a Record in Sequent, use the delete_all_records method. This method has 2 parameters:

  • the Record class
  • the where clause as a Hash (generally using the aggregate_id attribute)
class UserProjector < Sequent::Projector
  on UserDeleted do |event|
    delete_all_records(
      UserRecord,
      event.attributes.slice(:aggregate_id), # the where clause as a hash
    )
  end
end

Reading a record

You can also read a Record in a Projector by using the get_record method. This method has 2 parameters:

  • the Record class
  • the where clause as a Hash (generally using the aggregate_id attribute)

It is not a very common use case, but handy from time to time. For instance you could update the search column for a record for easy searching.

class UserProjector < Sequent::Projector
  on UserNameSet do |event|
    user_record = get_record!(UserRecord, event.attributes.slice(:aggregate_id))
    search_field = "#{user_record.search_field} #{event.firstname} #{event.lastname}"

    update_all_records(
      UserRecord,
      event.attributes.slice(:aggregate_id), # the where clause as a hash
      event.attributes.slice(:firstname, :lastname).merge(search_field: search_field) # the updates as a hash
    )
  end
end

Read-only records

Records written outside their Projector, for instance by a CommandHandler or a Workflow, are silently undone by the next replay, since a replay rebuilds a Projection from Events only. To prevent this, include Sequent::Core::ProjectionRecord in your Record classes:

class UserRecord < Sequent::ApplicationRecord
  include Sequent::Core::ProjectionRecord
end

The Records of such a class can then only be written by Projectors:

  • Saving, updating or destroying a Record fails with an ActiveRecord::ReadOnlyRecord error.
  • Deleting a Record, or writing Records without instantiating them (like insert_all, upsert_all, update_all and delete_all), fails with a Sequent::Core::ProjectionWrites::ForbiddenError.

Avoid callbacks that run when writing Records (like before_save or after_commit) and validations in such a Record class. These only run when a Projector saves a Record using the ActiveRecordPersistor, and not when replaying, so their logic belongs in the Projector, where it runs whichever persistor is used. Callbacks that run when reading Records, like after_find and after_initialize, are fine. A spec can check this for all Record classes of Projections using the have_no_write_callbacks matcher of Sequent::Test::ProjectionRecordHelpers, which ignores the callbacks ActiveRecord adds itself, for instance for associations:

require 'sequent/test'

describe 'projection records' do
  ActiveRecord::Base.descendants.select { |record_class| record_class < Sequent::Core::ProjectionRecord }
    .each do |record_class|
      it "#{record_class} has no write callbacks" do
        expect(record_class).to have_no_write_callbacks
      end
    end
end

Callbacks that must be kept anyway, like callbacks added by a gem, can be allowed by their method name, a regular expression matching it, or the class of the validator:

expect(UserRecord).to have_no_write_callbacks(allow: [:audit_changes, /\Aaudit_/, SomeGem::SomeValidator])

Projectors can always write the Records they manage, whichever persistor they use, also while the CommandService executes commands. Outside Projectors, writing is forbidden, unless it is allowed using Sequent::Core::ProjectionWrites. Record classes that do not include Sequent::Core::ProjectionRecord can be written as before.

Specs

Specs usually set up a Projection by creating its Records directly. Allow this for every example in your spec_helper.rb:

RSpec.configure do |config|
  config.around { |example| Sequent::Core::ProjectionWrites.allow { example.run } }
end

Writing is forbidden again while the specs execute commands, so a CommandHandler or Workflow that writes Records directly still fails, like it would in production.

Writing Records outside a Projector

Sometimes Records must be written outside their Projector on purpose, for instance when deleting all data of a customer, including the Events, or in a one-off data fix. Do this in Sequent::Core::ProjectionWrites.during_projection, which also applies when using a persistor directly:

Sequent::Core::ProjectionWrites.during_projection do
  UserRecord.where(aggregate_id: user_id).delete_all
end

A replay rebuilds the Records from the Events, so these changes do not survive it: the Events must also be deleted, or skipped while replaying, otherwise the Records reappear. See GDPR for ways to delete the data of a customer. To keep a change after a replay, record it in an Event that the Projector handles instead.

Writing Records using SQL directly (like ActiveRecord::Base.connection.execute) is not detected.

Known limitations

  1. You can not use belongs_to in your Record classes as these will fail if a parent relation does not exist. In a normal application flow this is not a problem, only when replaying Projections this can become a problem due to the order in which events are replayed. The only guarantee Sequent gives is that Events are replayed in order for a single Aggregate, but there is no guaranteed order between different Aggregates.
  2. For the same reason you can not use belongs_to you also can’t use foreign key constraints in your view schema. Relations between Aggregates are typically enforced in the Domain, so foreign key constraints are obsolete in the view schema. For performance reasons you can of course still add indices on your foreign key columns.