Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Sagas and compensation

After this lesson: I can work out the compensations a failed saga must run.

60 min lesson5 commandsDurable execution lab: crash a workflow on purpose and resume it from its journal

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

WordWhat it means
Transactionchanges a database makes all together or not at all
Sagaa workflow that undoes its finished steps when one fails
Compensationan action that undoes one step
Newest firstthe reverse of the order the steps ran
Irreversibleimpossible 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

Command
docker exec worker python3 saga.py trip-1 --fresh

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Book a trip whose car fails

Command
docker exec worker python3 saga.py trip-2 --fresh --fail-at book_car

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Read the bookings for trip-2

Command
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

Command
docker exec worker python3 saga.py trip-3 --fresh --fail-at book_car --crash-after 3

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Resume trip-3 into its compensations

Command
docker exec worker python3 saga.py trip-3 --fail-at book_car

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: the journal of trip-3

SeqStepResultWritten in run
0book_flightbooked flight1
1book_hotelbooked hotel1
2book_carfailed: no car left1
3cancel_hotelcancelled hotel2
4cancel_flightcancelled flight2

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

Code: python
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.

About this lab and its source: Durable execution lab: crash a workflow on purpose and resume it from its journal

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.