Skip to content

How to run an action in a database transaction

A MoveCargo action lifts tonnage out of one hold and adds it to another. When the second step fails, the first write has to vanish, and nobody should get a notice about a move that was rolled back.

The examples here are plain code, because the site’s bundle has no ActiveRecord. We ran them against in-memory SQLite, as the adapter’s own specs do.

The adapter is opt-in. transactional takes the model whose connection holds the transaction, either as a class or by name. You need ActiveRecord 7.1 or newer, and 7.2 for after_commit.

require 'actionable/rails'
class Hold < ActiveRecord::Base; end
class MoveCargo < Actionable::Action
transactional model: Hold
input do
required :source_id, :integer
required :target_id, :integer
required :tons, :integer
end
fails :hold_overdrawn
step :lift
step :stow
private
def lift
@source = Hold.find(input.source_id)
@source.update!(cargo_tons: @source.cargo_tons - input.tons)
end
def stow
fail!(:hold_overdrawn) if @source.cargo_tons.negative?
Hold.find(input.target_id).increment!(:cargo_tons, input.tons)
end
end

A success or a skip commits. A recorded failure rolls everything back and still returns the failure result, while an exception rolls back and keeps propagating.

port = Hold.create!(name: 'port', cargo_tons: 5)
starboard = Hold.create!(name: 'starboard', cargo_tons: 0)
MoveCargo.run(source_id: port.id, target_id: starboard.id, tons: 3).success? # => true
[port.reload.cargo_tons, starboard.reload.cargo_tons] # => [2, 3]
MoveCargo.run(source_id: port.id, target_id: starboard.id, tons: 9).code # => :hold_overdrawn
[port.reload.cargo_tons, starboard.reload.cargo_tons] # => [2, 3]

The second run pulled 9 tons from the port hold inside lift, and stow failed, so that write was undone.

after_commit declares a hook that fires once the outermost transaction has committed, and only following a success. A failure, a skip or a rollback never triggers it.

class MoveCargo < Actionable::Action
after_commit :announce
private
def announce
HarbourMailer.cargo_shifted(input.tons).deliver_later
end
end

The run has already finished when the hook fires, so it can’t alter the returned result. If it raises, the exception propagates from the point of the commit, after the writes are saved.

Inside a transaction that is already open, the action takes a savepoint of its own. A failed inner action undoes only its own writes, and the outer transaction keeps going and can still commit the rest.

Hold.transaction do
MoveCargo.run(source_id: port.id, target_id: starboard.id, tons: 9).code # => :hold_overdrawn
# the outer transaction is still open, with the failed move undone
end

To have the action join the outer transaction instead, pass requires_new: false to transactional. Either way, an after_commit hook waits for the outermost commit.

FieldStruct, Actionable and their adapters are open source under the MIT license.