What is a saga in a workflow?
A saga is a workflow whose steps each have a compensation, an action that undoes them. When a later step fails, the saga runs the compensations of the finished steps, newest first.
It is how a trip booking cancels the flight and the hotel when no car is left, even though three different companies took the bookings.
By the end of this lesson
Note
I can work out the compensations a failed saga must run.
Key words
| Word | What it means |
|---|---|
| Transaction | changes a database makes all together or not at all |
| Saga | a workflow that undoes its finished steps when one fails |
| Compensation | an action that undoes one step |
| Newest first | the reverse of the order the steps ran |
| Irreversible | impossible to undo, like an email already sent |
The cells students fill in are left blank in this preview.
One transaction cannot cover three companies
Inside one database, a transaction makes several changes all together or not at all. A trip is booked with an airline, a hotel and a car hire firm. Each has its own system, and none will join a transaction with the others.
So each booking is a separate step that really happens. If the car fails, the flight and the hotel are already booked, and something must undo them.
Book a whole trip
docker exec worker python3 saga.py trip-1 --freshShown here, not run. Press Start lab to type it into your own lab’s terminal.
Book a trip whose car fails
docker exec worker python3 saga.py trip-2 --fresh --fail-at book_carShown here, not run. Press Start lab to type it into your own lab’s terminal.
Read the bookings for trip-2
docker exec db psql -U durable -c "SELECT item, status FROM bookings WHERE workflow = 'trip-2' ORDER BY id"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Compensations are steps too
The engine writes the failed step to the journal, with its reason. Each compensation is an ordinary step, with its own row.
So a crash during the undo is safe. The next Runs crash trip-3 just after the car fails. The resume replays the three rows, sees the failure, and runs both compensations. A compensation is never forgotten half way.
Crash just after the car fails
docker exec worker python3 saga.py trip-3 --fresh --fail-at book_car --crash-after 3Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Resume trip-3 into its compensations
docker exec worker python3 saga.py trip-3 --fail-at book_carShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: the journal of trip-3
| Seq | Step | Result | Written in run |
|---|---|---|---|
| 0 | book_flight | booked flight | 1 |
| 1 | book_hotel | booked hotel | 1 |
| 2 | book_car | failed: no car left | 1 |
| 3 | cancel_hotel | cancelled hotel | 2 |
| 4 | cancel_flight | cancelled flight | 2 |
The cells students fill in are left blank in this preview.
A common mistake
Warning
Many people think a compensation puts the world back exactly as it was. It cannot unsend an email or unprint a ticket. A compensation is a new action, such as a refund or an apology, and some steps have none. Put those steps last.
Try it: a step with no undo
STEPS = [["book_flight", "cancel_flight"],
["book_hotel", "cancel_hotel"],
["send_ticket", None], # an email cannot be unsent
["book_car", "cancel_car"]]
FAILS = "book_car"
done = []
for pair in STEPS:
if pair[0] == FAILS:
print(pair[0], "failed")
break
print(pair[0], "ok")
done.append(pair)
done.reverse() # newest first
for pair in done:
if pair[1] is None:
print("no undo for", pair[0])
else:
print("compensate:", pair[1])
# Set FAILS = "book_hotel" and run it again.