Designing Objects in Rails
In this pack: sizing and rule strictness are set by the core
plugin's oo-design skill; each rule here keeps a core rule in this
language.
Overview
This skill holds only what Rails changes on top of oo-ruby: load that
skill too, because its rules on duck typing, modules and Data values
still hold in a Rails code base. Rails supplies Active Record,
whose instances stand for rows in a table, and callbacks that run inside the save;
the same rules now have new places to hide. A callback that writes a
second row, a controller that sets a guarded column with update, a
uniqueness validation with no index, and a model that gathers the
application's rules are the shapes this skill names. Rails 8.1 on Ruby
3.3 or later changes where these rules are kept, not what they require.
When to use
- An Active Record model holds a rule over several rows, or a request
that no single row holds.
- A callback writes another record, sends mail, enqueues a job, or
raises after the save has started.
- A controller or a view changes a guarded column with
update,
update_column, update_columns or update_all.
- A uniqueness validation is the only guard on a column.
- A service object, a form object or a query object is being weighed
against a model method.
- A model has grown rules that no longer match its table.
When not to use
- The code is plain Ruby that uses no Rails class, which
oo-ruby
covers.
- The question is how a view or a front-end component splits its state
from the domain: outside this skill, and
oo-separating-presentation-from-domain covers the core rule.
- A question no Rails feature changes, such as which object owns a
rule: the core skills, starting from
oo-design.
Core rules
Judgement. Keep a model an active record while its class mirrors
its table and holds few rules, and once its rules part from its
table, move them into plain Ruby objects that the model delegates to
or that a repository maps, as oo-taming-persistence rule 1 and
oo-working-within-a-framework rule 3 ask. An Active Record model
wraps one row: Rails pluralizes the class name to find the table,
infers the attributes from its columns, and lets an instance stand
for one row. That shape works while the fields and rules stay
close to that row. A rule that spans rows, or a request that no
single row holds, sits in the class only by reaching across the
table it mirrors, so it moves to a plain Ruby object: the model
delegates to the object, or a repository maps between the row and
the object. Rails still supplies the table, the connection and the
migration; the rule no longer has to match a column.
Rule. Let no callback hold a business rule or reach another record
or another system: the use case calls those effects itself, and work
for another system waits for the commit, through
transaction.after_commit or a job enqueued after it, as
oo-working-within-a-framework rule 1 and
oo-publishing-domain-events rule 3 ask. A callback runs when
Rails changes an object: after_create, after_save and their kin
run inside the save, and the save is wrapped in a transaction. A
callback that writes a second record writes it on every path that
saves the first, and a callback that sends a message can send it for
a change that then rolls back. An exception in after_save rolls
the transaction back, which shows the callback runs before the
commit. The use case calls the second write and the outside work
itself. When the work is for another system, it waits:
transaction.after_commit runs after the transaction has committed.
after_commit and after_rollback do not run until the database
changes have been committed or rolled back, which is when a model's
commit callbacks run. Neither callback is where the outside work
goes; the use case's transaction.after_commit is.
Rule. Change state that a rule guards only in a model method named
for the action, which checks the rule and raises before anything
changes; no controller sends update(status: ...), no code assigns
the guarded attribute outside that method, and no code uses
update_column, update_columns or update_all on that state, as
oo-encapsulating-state-and-behaviour rules 1 and 3,
oo-designing-repositories rule 6 and
oo-designing-failure-behaviour rule 4 ask. update_column,
update_columns and update_all skip validations and save
regardless of validity, and the same three skip callbacks. update
runs validations and callbacks. A controller that sends
update(status: ...) decides the rule in the edge, and a second path
with update_column writes the guarded column with no rule at all.
The model method named for the action reads the current state, raises
when the rule refuses, and only then writes, so every caller reaches
the same check and nothing changes on a refused call. Active Record
defines a public writer for every column of its table, status=
beside status, so oo-ruby rule 3, which asks for readers only, is
relaxed for those generated attribute writers. The writer is not a
domain action: this rule forbids assigning the guarded attribute
outside the action method. The bang save methods raise
ActiveRecord::RecordInvalid on a failed validation; save and
update return false, which a caller that ignores it never sees.
Default. Put a use case that changes more than one model, or a
request that maps onto no model, in a plain Ruby object: a service
object that runs one transaction around one aggregate's change, or a
form object built on ActiveModel::Model, as
oo-placing-domain-logic rules 2 and 5, oo-designing-aggregates
rule 4 and oo-working-within-a-framework rule 2 ask. A
controller that loads several models, checks their rules and saves
them keeps the use case in the edge: a test needs a request to run
it, and a second entry point cannot reach it. A service object is a
plain Ruby object that takes its collaborators through its
constructor, loads the aggregate, sends the commands and opens one
transaction. A form object holds a request's attributes and
validations with no table behind it; ActiveModel::Model includes
ActiveModel::API, so it works with form_with and validations, and
it is the shape for a model-like Ruby class with no table. The exception
is a request that maps onto no model and changes nothing, such as a
search that applies no business rule: it needs no service or form
object, because a read query answers it and the read decides no rule
(rule 5).
Default. Name each read for the question it answers, in a scope or
a query object, and keep where chains out of controllers and
views, as oo-designing-repositories rules 3 and 4 and
oo-layering-the-system rule 6 ask. A scope reads as one clinic
question at its call site, so Appointment.for_clinician_on says what
comes back, while a where in a controller leaves the question
spelled in the edge and each caller writes its own version of it. A
query object carries criteria that combine freely. A scope always
returns an ActiveRecord::Relation, even when its condition is
false, while a class method with a conditional can return nil;
that difference makes the scope the shape that still chains.
The exception is a read of one row already named by an identity, such
as a show action loading the record whose id the request carries: it
needs no scope, because the caller already names the row.
Rule. Hold a rule over many rows, such as one booked appointment
per slot, with a database constraint, because a uniqueness
validation alone does not hold when two saves run at once, as
oo-designing-aggregates rule 6 and
oo-working-within-a-framework rule 1 ask. validates :slot_id, uniqueness: true finds no row with the value and creates no
constraint in the database, so two connections can both find no row
and both save. The validation creates no uniqueness constraint, so
the unique index must be added, through add_index with
unique: true in a migration. The database
constraint refuses the second save whatever the application did
first, so one model's method cannot keep the rule alone: the index
sees every writer.
Pattern
Consent records a patient's consent to a treatment. It is an Active
Record model with status, given_at, withdrawn_at and
lock_version columns, and its status a rule guards: only a pending
consent may be given, and only a given consent may be withdrawn. The
first fence is a controller that decides both rules and writes the
status itself, including one path with update_column. The second
fence moves each check into the model's action method and calls it from
a service object that opens one transaction.
Before:
class ConsentsController < ApplicationController
def update
consent = Consent.find(params[:id])
if consent.status == "pending"
consent.update(status: "given")
redirect_to consent
else
render :edit
end
end
def withdraw
consent = Consent.find(params[:id])
consent.update_column(:status, "withdrawn")
redirect_to consent
end
end
In the Before, update reads status, decides whether the consent may
be given, and writes the guarded column with update, so the controller
owns the rule (rule 3). withdraw writes the same column with
update_column, which skips validations and callbacks, so no rule runs
on that path at all (rule 3). The fence stores a consent row under its
id in the consents table; the controller opens no transaction of its
own.
After:
class ConsentAlreadyGiven < StandardError; end
class ConsentNotGiven < StandardError; end
class Consent < ApplicationRecord
def give(at:)
raise ConsentAlreadyGiven, "consent #{id} is not pending" unless
status == "pending"
update!(status: "given", given_at: at)
rescue ActiveRecord::StaleObjectError
raise ConsentAlreadyGiven, "consent #{id} is not pending"
end
def withdraw(at:)
raise ConsentNotGiven, "consent #{id} was not given" unless
status == "given"
update!(status: "withdrawn", withdrawn_at: at)
rescue ActiveRecord::StaleObjectError
raise ConsentNotGiven, "consent #{id} was not given"
end
end
class GiveConsent
def call(consent_id:, at:)
Consent.transaction do
Consent.find(consent_id).give(at: at)
end
end
end
class WithdrawConsent
def call(consent_id:, at:)
Consent.transaction do
Consent.find(consent_id).withdraw(at: at)
end
end
end
In the After, Consent#give and Consent#withdraw are named for the
actions; each checks the status and raises ConsentAlreadyGiven or
ConsentNotGiven before it writes, so nothing changes on a refused call
(rule 3). Two copies of the same consent, both loaded before either
saves, pass that check, because each read the status its action
expects; what refuses the second caller is the version guard.
The consents table holds an integer lock_version column, and Active
Record's optimistic locking reads it with the row and adds the version
it read to the save's condition. The first call writes the guarded
status, its timestamp and the next version; a second copy loaded before
that write matches no row, so its save raises
ActiveRecord::StaleObjectError, which give or withdraw turns into
its own refusal. That guard needs no row lock, so it refuses the second
caller on every store Rails supports. A caller sees
ConsentAlreadyGiven, ConsentNotGiven or, on a validation failure,
ActiveRecord::RecordInvalid (rule 3), and the guard's store error
never leaves the action. GiveConsent and WithdrawConsent are
plain Ruby service objects: each loads the consent, sends it one action
message, and opens one transaction around that one aggregate's change
(rule 4). The controller calls one of them. update! runs validations
inside the transaction, and the model's class still mirrors its table.
The fence shows the types in one file for reading. The fence stores a
consent row under its id in the consents table, inside the transaction
the service object opens: the guarded status, its timestamp and
lock_version change in that one save. The state keeps rules 3 and 4:
every change goes through the action method, and each service object
opens one transaction around one aggregate.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A callback that changes another record, sends mail, enqueues a job or
calls an outside service.
- A model that knows a second model's rules or writes its rows.
- A controller or a view with a
where chain, or a scope named after a
column instead of a question.
update, update_column, update_columns or update_all on a
column a rule guards.
- A uniqueness validation with no unique index in the schema.
- A service object that changes several aggregates in one transaction.
- A form object whose
save writes models with no transaction.
- A model whose rules no longer match the columns it mirrors.
- A callback that holds a business rule, whatever its timing.
Common mistakes
- Adding a callback because several paths save the record, so every path
gets the effect, intended or not.
- Trusting
validates :slot_id, uniqueness: true to hold when two
saves run at once.
- Calling
update_column to skip callbacks without noticing the rules
those callbacks held.
- Moving a controller action into a model and calling it a service
object.
- Giving a form object a
save that writes several models outside one
transaction.
- Using a scope whose name states a rule, such as
available, and
letting a caller decide what the rule means.
- Treating
after_commit as a place for a business rule.
- Keeping every rule on one large model because Active Record makes
saving convenient.
Related skills
oo-ruby holds the language rules this skill applies, including its
rules on duck typing, modules and Data values.
oo-taming-persistence decides between an active record and a data
mapper, and keeps a lazy load inside its transaction.
oo-working-within-a-framework decides what a framework may shape
and what stays in the domain.
oo-publishing-domain-events says what an event is and when a
reaction runs.
oo-placing-domain-logic places a use case and its transaction.
oo-designing-aggregates decides what one transaction changes.
oo-designing-repositories declares a read and a repository in the
domain's words.
oo-encapsulating-state-and-behaviour keeps state behind methods
named for actions.
oo-designing-failure-behaviour names a refusal and raises it before
a change.
oo-layering-the-system keeps a read that decides nothing out of the
domain.
oo-separating-presentation-from-domain splits a screen's state from
the domain.
Further reading
1---2name: oo-ruby-rails3description: Use when a Rails app's Active Record models gather rules, callbacks hide side effects, or a service or query object is being weighed.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-ruby-rails7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Designing Objects in Rails1213**In this pack:** sizing and rule strictness are set by the core14plugin's `oo-design` skill; each rule here keeps a core rule in this15language.1617## Overview1819This skill holds only what Rails changes on top of `oo-ruby`: load that20skill too, because its rules on duck typing, modules and `Data` values21still hold in a Rails code base. Rails supplies Active Record,22whose instances stand for rows in a table, and callbacks that run inside the save;23the same rules now have new places to hide. A callback that writes a24second row, a controller that sets a guarded column with `update`, a25uniqueness validation with no index, and a model that gathers the26application's rules are the shapes this skill names. Rails 8.1 on Ruby273.3 or later changes where these rules are kept, not what they require.2829## When to use3031- An Active Record model holds a rule over several rows, or a request32 that no single row holds.33- A callback writes another record, sends mail, enqueues a job, or34 raises after the save has started.35- A controller or a view changes a guarded column with `update`,36 `update_column`, `update_columns` or `update_all`.37- A uniqueness validation is the only guard on a column.38- A service object, a form object or a query object is being weighed39 against a model method.40- A model has grown rules that no longer match its table.4142## When not to use4344- The code is plain Ruby that uses no Rails class, which `oo-ruby`45 covers.46- The question is how a view or a front-end component splits its state47 from the domain: outside this skill, and48 `oo-separating-presentation-from-domain` covers the core rule.49- A question no Rails feature changes, such as which object owns a50 rule: the core skills, starting from `oo-design`.5152## Core rules53541. Judgement. **Keep a model an active record while its class mirrors55 its table and holds few rules, and once its rules part from its56 table, move them into plain Ruby objects that the model delegates to57 or that a repository maps, as `oo-taming-persistence` rule 1 and58 `oo-working-within-a-framework` rule 3 ask.** An Active Record model59 wraps one row: Rails pluralizes the class name to find the table,60 infers the attributes from its columns, and lets an instance stand61 for one row. That shape works while the fields and rules stay62 close to that row. A rule that spans rows, or a request that no63 single row holds, sits in the class only by reaching across the64 table it mirrors, so it moves to a plain Ruby object: the model65 delegates to the object, or a repository maps between the row and66 the object. Rails still supplies the table, the connection and the67 migration; the rule no longer has to match a column.68692. Rule. **Let no callback hold a business rule or reach another record70 or another system: the use case calls those effects itself, and work71 for another system waits for the commit, through72 `transaction.after_commit` or a job enqueued after it, as73 `oo-working-within-a-framework` rule 1 and74 `oo-publishing-domain-events` rule 3 ask.** A callback runs when75 Rails changes an object: `after_create`, `after_save` and their kin76 run inside the save, and the save is wrapped in a transaction. A77 callback that writes a second record writes it on every path that78 saves the first, and a callback that sends a message can send it for79 a change that then rolls back. An exception in `after_save` rolls80 the transaction back, which shows the callback runs before the81 commit. The use case calls the second write and the outside work82 itself. When the work is for another system, it waits:83 `transaction.after_commit` runs after the transaction has committed.84 `after_commit` and `after_rollback` do not run until the database85 changes have been committed or rolled back, which is when a model's86 commit callbacks run. Neither callback is where the outside work87 goes; the use case's `transaction.after_commit` is.88893. Rule. **Change state that a rule guards only in a model method named90 for the action, which checks the rule and raises before anything91 changes; no controller sends `update(status: ...)`, no code assigns92 the guarded attribute outside that method, and no code uses93 `update_column`, `update_columns` or `update_all` on that state, as94 `oo-encapsulating-state-and-behaviour` rules 1 and 3,95 `oo-designing-repositories` rule 6 and96 `oo-designing-failure-behaviour` rule 4 ask.** `update_column`,97 `update_columns` and `update_all` skip validations and save98 regardless of validity, and the same three skip callbacks. `update`99 runs validations and callbacks. A controller that sends100 `update(status: ...)` decides the rule in the edge, and a second path101 with `update_column` writes the guarded column with no rule at all.102 The model method named for the action reads the current state, raises103 when the rule refuses, and only then writes, so every caller reaches104 the same check and nothing changes on a refused call. Active Record105 defines a public writer for every column of its table, `status=`106 beside `status`, so `oo-ruby` rule 3, which asks for readers only, is107 relaxed for those generated attribute writers. The writer is not a108 domain action: this rule forbids assigning the guarded attribute109 outside the action method. The bang save methods raise110 `ActiveRecord::RecordInvalid` on a failed validation; `save` and111 `update` return false, which a caller that ignores it never sees.1121134. Default. **Put a use case that changes more than one model, or a114 request that maps onto no model, in a plain Ruby object: a service115 object that runs one transaction around one aggregate's change, or a116 form object built on `ActiveModel::Model`, as117 `oo-placing-domain-logic` rules 2 and 5, `oo-designing-aggregates`118 rule 4 and `oo-working-within-a-framework` rule 2 ask.** A119 controller that loads several models, checks their rules and saves120 them keeps the use case in the edge: a test needs a request to run121 it, and a second entry point cannot reach it. A service object is a122 plain Ruby object that takes its collaborators through its123 constructor, loads the aggregate, sends the commands and opens one124 transaction. A form object holds a request's attributes and125 validations with no table behind it; `ActiveModel::Model` includes126 `ActiveModel::API`, so it works with `form_with` and validations, and127 it is the shape for a model-like Ruby class with no table. The exception128 is a request that maps onto no model and changes nothing, such as a129 search that applies no business rule: it needs no service or form130 object, because a read query answers it and the read decides no rule131 (rule 5).1321335. Default. **Name each read for the question it answers, in a scope or134 a query object, and keep `where` chains out of controllers and135 views, as `oo-designing-repositories` rules 3 and 4 and136 `oo-layering-the-system` rule 6 ask.** A scope reads as one clinic137 question at its call site, so `Appointment.for_clinician_on` says what138 comes back, while a `where` in a controller leaves the question139 spelled in the edge and each caller writes its own version of it. A140 query object carries criteria that combine freely. A scope always141 returns an `ActiveRecord::Relation`, even when its condition is142 false, while a class method with a conditional can return `nil`;143 that difference makes the scope the shape that still chains.144 The exception is a read of one row already named by an identity, such145 as a show action loading the record whose id the request carries: it146 needs no scope, because the caller already names the row.1471486. Rule. **Hold a rule over many rows, such as one booked appointment149 per slot, with a database constraint, because a `uniqueness`150 validation alone does not hold when two saves run at once, as151 `oo-designing-aggregates` rule 6 and152 `oo-working-within-a-framework` rule 1 ask.** `validates :slot_id,153 uniqueness: true` finds no row with the value and creates no154 constraint in the database, so two connections can both find no row155 and both save. The validation creates no uniqueness constraint, so156 the unique index must be added, through `add_index` with157 `unique: true` in a migration. The database158 constraint refuses the second save whatever the application did159 first, so one model's method cannot keep the rule alone: the index160 sees every writer.161162## Pattern163164`Consent` records a patient's consent to a treatment. It is an Active165Record model with `status`, `given_at`, `withdrawn_at` and166`lock_version` columns, and its status a rule guards: only a pending167consent may be given, and only a given consent may be withdrawn. The168first fence is a controller that decides both rules and writes the169status itself, including one path with `update_column`. The second170fence moves each check into the model's action method and calls it from171a service object that opens one transaction.172173Before:174175```ruby176class ConsentsController < ApplicationController177 def update178 consent = Consent.find(params[:id])179 if consent.status == "pending"180 consent.update(status: "given")181 redirect_to consent182 else183 render :edit184 end185 end186187 def withdraw188 consent = Consent.find(params[:id])189 consent.update_column(:status, "withdrawn")190 redirect_to consent191 end192end193```194195In the Before, `update` reads `status`, decides whether the consent may196be given, and writes the guarded column with `update`, so the controller197owns the rule (rule 3). `withdraw` writes the same column with198`update_column`, which skips validations and callbacks, so no rule runs199on that path at all (rule 3). The fence stores a consent row under its200id in the consents table; the controller opens no transaction of its201own.202203After:204205```ruby206class ConsentAlreadyGiven < StandardError; end207208class ConsentNotGiven < StandardError; end209210class Consent < ApplicationRecord211 def give(at:)212 raise ConsentAlreadyGiven, "consent #{id} is not pending" unless213 status == "pending"214215 update!(status: "given", given_at: at)216 rescue ActiveRecord::StaleObjectError217 raise ConsentAlreadyGiven, "consent #{id} is not pending"218 end219220 def withdraw(at:)221 raise ConsentNotGiven, "consent #{id} was not given" unless222 status == "given"223224 update!(status: "withdrawn", withdrawn_at: at)225 rescue ActiveRecord::StaleObjectError226 raise ConsentNotGiven, "consent #{id} was not given"227 end228end229230class GiveConsent231 def call(consent_id:, at:)232 Consent.transaction do233 Consent.find(consent_id).give(at: at)234 end235 end236end237238class WithdrawConsent239 def call(consent_id:, at:)240 Consent.transaction do241 Consent.find(consent_id).withdraw(at: at)242 end243 end244end245```246247In the After, `Consent#give` and `Consent#withdraw` are named for the248actions; each checks the status and raises `ConsentAlreadyGiven` or249`ConsentNotGiven` before it writes, so nothing changes on a refused call250(rule 3). Two copies of the same consent, both loaded before either251saves, pass that check, because each read the status its action252expects; what refuses the second caller is the version guard.253The consents table holds an integer `lock_version` column, and Active254Record's optimistic locking reads it with the row and adds the version255it read to the save's condition. The first call writes the guarded256status, its timestamp and the next version; a second copy loaded before257that write matches no row, so its save raises258`ActiveRecord::StaleObjectError`, which `give` or `withdraw` turns into259its own refusal. That guard needs no row lock, so it refuses the second260caller on every store Rails supports. A caller sees261`ConsentAlreadyGiven`, `ConsentNotGiven` or, on a validation failure,262`ActiveRecord::RecordInvalid` (rule 3), and the guard's store error263never leaves the action. `GiveConsent` and `WithdrawConsent` are264plain Ruby service objects: each loads the consent, sends it one action265message, and opens one transaction around that one aggregate's change266(rule 4). The controller calls one of them. `update!` runs validations267inside the transaction, and the model's class still mirrors its table.268The fence shows the types in one file for reading. The fence stores a269consent row under its id in the consents table, inside the transaction270the service object opens: the guarded status, its timestamp and271`lock_version` change in that one save. The state keeps rules 3 and 4:272every change goes through the action method, and each service object273opens one transaction around one aggregate.274275## Red flags276277Places to look, not verdicts. A red flag becomes a finding only with278evidence: a measurement, a reproducible bug, or a failing test.279280- A callback that changes another record, sends mail, enqueues a job or281 calls an outside service.282- A model that knows a second model's rules or writes its rows.283- A controller or a view with a `where` chain, or a scope named after a284 column instead of a question.285- `update`, `update_column`, `update_columns` or `update_all` on a286 column a rule guards.287- A uniqueness validation with no unique index in the schema.288- A service object that changes several aggregates in one transaction.289- A form object whose `save` writes models with no transaction.290- A model whose rules no longer match the columns it mirrors.291- A callback that holds a business rule, whatever its timing.292293## Common mistakes294295- Adding a callback because several paths save the record, so every path296 gets the effect, intended or not.297- Trusting `validates :slot_id, uniqueness: true` to hold when two298 saves run at once.299- Calling `update_column` to skip callbacks without noticing the rules300 those callbacks held.301- Moving a controller action into a model and calling it a service302 object.303- Giving a form object a `save` that writes several models outside one304 transaction.305- Using a scope whose name states a rule, such as `available`, and306 letting a caller decide what the rule means.307- Treating `after_commit` as a place for a business rule.308- Keeping every rule on one large model because Active Record makes309 saving convenient.310311## Related skills312313- `oo-ruby` holds the language rules this skill applies, including its314 rules on duck typing, modules and `Data` values.315- `oo-taming-persistence` decides between an active record and a data316 mapper, and keeps a lazy load inside its transaction.317- `oo-working-within-a-framework` decides what a framework may shape318 and what stays in the domain.319- `oo-publishing-domain-events` says what an event is and when a320 reaction runs.321- `oo-placing-domain-logic` places a use case and its transaction.322- `oo-designing-aggregates` decides what one transaction changes.323- `oo-designing-repositories` declares a read and a repository in the324 domain's words.325- `oo-encapsulating-state-and-behaviour` keeps state behind methods326 named for actions.327- `oo-designing-failure-behaviour` names a refusal and raises it before328 a change.329- `oo-layering-the-system` keeps a read that decides nothing out of the330 domain.331- `oo-separating-presentation-from-domain` splits a screen's state from332 the domain.333334## Further reading335336- [Callbacks to use cases](references/callbacks-to-use-cases.md)