Module 10 · Lesson 8 of 12Free

Sagas: multi-step transactions with rollback steps

Level

Advanced

Topic

Consensus, coordination and distributed transactions

Reading time

19 min

Kartly reserves one item for Asha, reducing available stock from 10 to 9. Another checkout reserves an item. Then Asha’s payment is declined.

Should Kartly restore stock to 10, or increase it by one?

Kartly now has separate order, inventory and payment services. How can checkout recover from partial success without reversing someone else’s work?

Undo the action, not history

A database rollback abandons changes before their transaction commits. Asha’s inventory transaction has already committed. Recovery needs another transaction: release her particular reservation.

A saga is a sequence of local transactions with recovery actions for partial completion. Each local transaction commits independently. A compensation is a later business action that counteracts an earlier action.^{1Saga patternsAmazon Web Services, AWS Prescriptive Guidance}

The phrase “rollback steps” can suggest a stronger promise than sagas provide. Other requests can observe intermediate committed changes. Compensation also leaves history: a payment hold and its cancellation may both remain visible.^{2Saga distributed transactions patternMicrosoft, Azure Architecture Center}

For this lesson’s scenario, Asha buys one item costing ₹2,400. Checkout reserves stock, authorizes payment, then confirms the order. Authorization creates a temporary payment hold, not a completed charge.

The product promise is specific: no order becomes confirmed without stock and authorization. An unsuccessful checkout eventually releases its resources, assuming dependencies recover or an operator resolves the problem.

That promise allows a visible PENDING state. It does not promise that every service changes at one instant.

Choose a recoverable business boundary

Start with three ordinary calls:

1. Create a pending order.
2. Reserve its stock.
3. Authorize payment and confirm the order.

This works until a later call fails. Adding try and except around the calls handles some errors, but not a server crash. Local variables disappear before cleanup runs.

The earlier two-phase commit lesson coordinates a shared commit decision. A saga instead accepts partial commits and defines what happens next.

Before implementation, give each action an owner and a recovery rule.

Order confirmation finishes this saga. Later customer cancellation belongs to a separate workflow with different rules.

Do not dispatch a parcel during these reversible steps. You cannot make a delivered parcel disappear. Place irreversible work behind a deliberate business boundary, then recover forward when reversal is no longer meaningful.^{2Saga distributed transactions patternMicrosoft, Azure Architecture Center}

The remaining question is who remembers the sequence when a worker disappears.

Put progress somewhere durable

Orchestration puts workflow decisions in a coordinator. Choreography distributes those decisions among services reacting to events. Both arrangements can implement sagas.^{1Saga patternsAmazon Web Services, AWS Prescriptive Guidance}

Inventory’s database belongs to Inventory; Payments owns its operation store. Neither service lets the coordinator write those records directly.

The normal write path is:

1. Orders stores the pending order and initial command intent in one local transaction.
2. A worker reads the intent and asks Inventory to reserve stock.
3. Inventory commits its reservation and returns the saved result.
4. Orders records that result and the payment command intent together.
5. Payments resolves authorization; Orders then attempts confirmation.
6. Orders commits CONFIRMED and the workflow’s terminal state together.

The read path is shorter: the app asks Orders for the order’s current status. It does not assemble a status from several services.

Saving intent before sending makes a crashed worker replaceable. It also means a replacement may send the same command again.

Repeat commands without repeating effects

The app supplies an idempotency key for one checkout intention. Orders stores a unique mapping from customer and key to order. A retry returns that order; changed input with the same key is rejected.

Participants need their own stable operation identities.

These are Kartly’s illustrative internal contracts, not provider APIs. Authentication errors and malformed requests remain ordinary request errors.

Each participant compares repeated input with its stored input. Reusing auth-17 for a different amount must not silently return an unrelated authorization.

Inventory enforces available stock inside one local transaction. It creates the reservation and conditionally reduces availability. A failed stock check leaves no active reservation. Repeated calls return the existing result instead of decrementing again.

Release changes ACTIVE to RELEASED and increments availability in the same transaction. A second release sees RELEASED and does nothing. The local locking details build on isolation levels and locking.

Do not delete released reservations immediately. Their terminal state stops a delayed reserve request from recreating the reservation. If release arrives before reserve, store a terminal cancellation record for that ID.

Payments has a harder boundary: its database cannot atomically commit a provider call. It records the operation first, uses the same provider key on retries, and queries unresolved operations. These capabilities are requirements for the provider selected in this scenario.

That still leaves a distinction the coordinator must preserve: rejection is not the same as silence.

A timeout leaves work unresolved

Suppose Payments obtains authorization, but its reply never reaches Orders. The customer sees “Payment processing”.

If Orders treats this timeout as a decline, it could release stock while a payment hold remains active. A retry with a fresh identity could also create another hold.

Instead, retain the authorization phase. Retry or query the same operation until its outcome is known. Only a definitive rejection selects the failure branch.

The coordinator’s state machine separates forward work from compensation:

An unknown outcome leaves every phase unchanged. A definitive confirmation rejection might occur because an order-owned business rule no longer permits checkout.

For this sequence, compensation cancels authorization before releasing stock. This keeps the item reserved while payment cleanup remains unresolved. Releasing stock first could improve availability, but needs an explicit policy for customers whose holds remain active.

A deadline should trigger resolution or escalation, not invent a failure result. Customer cancellation during an unresolved authorization also requires resolving or safely cancelling that same operation.

Now the phase table can become executable logic.

Make transitions small and guarded

The coordinator owns this compact record:

CREATE TABLE checkout_workflows (
  order_id TEXT PRIMARY KEY,
  phase TEXT NOT NULL CHECK (phase IN (
    'RESERVING', 'AUTHORIZING', 'CONFIRMING',
    'VOIDING', 'RELEASING', 'COMPLETED', 'CANCELLED'
  )),
  version BIGINT NOT NULL DEFAULT 0,
  expected_operation TEXT NOT NULL,
  next_attempt_at TIMESTAMPTZ NOT NULL,
  last_error TEXT
);

CREATE INDEX checkout_workflows_due
ON checkout_workflows (next_attempt_at)
WHERE phase NOT IN ('COMPLETED', 'CANCELLED');

The index serves workers finding due, unfinished workflows. A separate command record stores the operation ID, action, immutable request and result.

The following function implements only transition selection. It performs no network calls and makes no durability claim.

from typing import Literal

Outcome = Literal["ok", "rejected", "unknown"]

SUCCESS: dict[str, str] = {
    "RESERVING": "AUTHORIZING",
    "AUTHORIZING": "CONFIRMING",
    "CONFIRMING": "COMPLETED",
    "VOIDING": "RELEASING",
    "RELEASING": "CANCELLED",
}
REJECTION: dict[str, str] = {
    "RESERVING": "CANCELLED",
    "AUTHORIZING": "RELEASING",
    "CONFIRMING": "VOIDING",
}

def next_phase(phase: str, outcome: Outcome) -> str:
    if phase not in SUCCESS:
        raise ValueError("Expected an active phase")
    if outcome == "unknown":
        return phase
    if outcome == "ok":
        return SUCCESS[phase]
    return REJECTION.get(phase, phase)

type Outcome = "ok" | "rejected" | "unknown";

const success = new Map<string, string>([
  ["RESERVING", "AUTHORIZING"],
  ["AUTHORIZING", "CONFIRMING"],
  ["CONFIRMING", "COMPLETED"],
  ["VOIDING", "RELEASING"],
  ["RELEASING", "CANCELLED"],
]);
const rejection = new Map<string, string>([
  ["RESERVING", "CANCELLED"],
  ["AUTHORIZING", "RELEASING"],
  ["CONFIRMING", "VOIDING"],
]);

function nextPhase(phase: string, outcome: Outcome): string {
  const target = success.get(phase);
  if (target === undefined) {
    throw new Error("Expected an active phase");
  }
  if (outcome === "unknown") return phase;
  if (outcome === "ok") return target;
  return rejection.get(phase) ?? phase;
}

The surrounding worker must validate that a reply matches expected_operation. It then commits the result, phase change and next command intent together.

Two workers may read the same version. Use a conditional update:

UPDATE checkout_workflows
SET phase = $1,
    expected_operation = $2,
    next_attempt_at = $3,
    version = version + 1
WHERE order_id = $4
  AND version = $5
  AND expected_operation = $6
RETURNING version;

Only the winning transaction inserts the next intent. A worker that updates zero rows reloads instead of advancing stale state.

This protects local decisions, not remote effects. Stable participant operation IDs protect repeated remote commands. Both mechanisms are necessary.

Recovery includes unfinished compensation

Compensation can fail, and sagas provide no automatic isolation across services.^{2Saga distributed transactions patternMicrosoft, Azure Architecture Center} Kartly must therefore treat unfinished recovery as durable work, not an exception message.

Retry transient failures with increasing delays and randomness. Do not let thousands of recovering workflows hammer an unhealthy dependency. Separate forward-work capacity from compensation capacity so new checkouts cannot starve cleanup.

A compensation attempt limit should move work to operator attention, not erase it. Keep the obligation visible until the effect is resolved. CANCELLED means cleanup completed under this contract, not merely that the customer requested cancellation.

Reservations also need a lifetime policy. If Inventory expires them independently, Orders must validate or finalize the reservation before confirmation. Otherwise payment could succeed after stock has been returned to sale.

For this lesson, reservations remain active until explicit release or successful checkout handoff. Production retention and expiry rules must account for unresolved payment operations.

Common mistakes

• Calling compensation a database rollback. It is a new committed action. It cannot hide everything observers already saw.
• Sending a new operation ID after timeout. That creates a new intention instead of resolving the existing one.
• Restoring an old stock value. Release the identified reservation; preserve other buyers’ changes.
• Keeping recovery only in memory. A crash must leave enough durable information for another worker.
• Treating events as proof of delivery. Saving a phase does not prove that the next service received its command.

Going deeper

Where this shows up

• Design: a concert ticket booking system: seat holds need payment-aware release rules.
• Design: a payment processing system: unresolved external effects require durable reconciliation.
• Design: an e-commerce checkout: stock, payment and order state need a shared recovery plan.

The next problem is making a saved transition produce its outgoing message despite a crash, covered in Transactional outbox.

Check your understanding

Summary