Projector
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:
- A Projector. Responsible for creating Projections. We are discussing Projectors in this chapter.
- A Record class. This is a
Sequent::ApplicationRecordclass, subclassingActiveRecord::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 includeSequent::Core::ProjectionRecord, see Read-only records. - 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:
- A Record can only be managed by one Projector. A Projector can however manage multiple Records.
- A Projector should only access Records it manages.
A Projector is used in two different stages in your application.
- During normal operation. This is when your application is running and Events are coming in. The Projector updates the Records as you specified.
- 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 theaggregate_idattribute) - 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 theaggregate_idattribute)
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 theaggregate_idattribute)
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::ReadOnlyRecorderror. - Deleting a Record, or writing Records without instantiating them (like
insert_all,upsert_all,update_allanddelete_all), fails with aSequent::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
- You can not use
belongs_toin 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. - For the same reason you can not use
belongs_toyou 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.