Prerequisites

The Problem Sagas Address

Two-phase commit holds locks across a network for the duration of a transaction. For a business process spanning seconds, minutes, or days, that is untenable. Sagas abandon atomicity to keep each step short and local.

Compensation Is Not Rollback

This distinction is the source of most saga design errors. A rollback erases history; a compensation adds to it.

Irreversible Steps

Some actions cannot be compensated at all. Their placement determines whether a saga is viable.

Modelling a Saga

const ORDER_SAGA = {
    name: "place-order",
    steps: [
        {
            name: "reserve-inventory",
            type: "compensatable",
            action: (ctx) => inventory.reserve(ctx.orderId, ctx.items),
            compensation: (ctx) => inventory.release(ctx.orderId)
        },
        {
            name: "authorize-payment",
            type: "compensatable",
            action: (ctx) => payments.authorize(ctx.orderId, ctx.amount),
            compensation: (ctx) => payments.voidAuthorization(ctx.orderId)
        },
        {
            name: "capture-payment",
            type: "pivot",
            action: (ctx) => payments.capture(ctx.orderId),
            compensation: (ctx) => payments.refund(ctx.orderId)
        },
        {
            name: "commit-inventory",
            type: "retriable",
            action: (ctx) => inventory.commit(ctx.orderId)
        },
        {
            name: "create-shipment",
            type: "retriable",
            action: (ctx) => shipping.create(ctx.orderId, ctx.address)
        },
        {
            name: "notify-customer",
            type: "retriable",
            action: (ctx) => notifications.orderConfirmed(ctx.orderId)
        }
    ]
};

async function executeSaga(definition, context, log) {
    const completed = [];

    for (const step of definition.steps) {
        try {
            await log.record(context.sagaId, step.name, "started");

            const result = await step.action(context);

            await log.record(context.sagaId, step.name, "completed", result);
            completed.push(step);
        } catch (error) {
            await log.record(context.sagaId, step.name, "failed", error);

            if (step.type === "retriable") {
                await log.markForRetry(context.sagaId, step.name);
                return { status: "awaiting-retry", failedAt: step.name };
            }

            await compensate(completed, context, log);
            return { status: "compensated", failedAt: step.name };
        }
    }

    await log.record(context.sagaId, null, "saga-completed");
    return { status: "completed" };
}

async function compensate(completedSteps, context, log) {
    for (const step of completedSteps.slice().reverse()) {
        if (!step.compensation) continue;

        await retryWithBackoff(async () => {
            await step.compensation(context);
            await log.record(context.sagaId, step.name, "compensated");
        }, { maxAttempts: 10 });
    }
}

Choreography Versus Orchestration

Two coordination styles exist, and the choice determines where workflow knowledge lives.

Choreography Flow

// Each service reacts to events and emits its own
inventoryService.on("OrderCreated", async (event) => {
    try {
        await inventory.reserve(event.orderId, event.items);
        await publish("InventoryReserved", { orderId: event.orderId });
    } catch (error) {
        await publish("InventoryReservationFailed", {
            orderId: event.orderId,
            reason: error.message
        });
    }
});

inventoryService.on("PaymentFailed", async (event) => {
    await inventory.release(event.orderId);
    await publish("InventoryReleased", { orderId: event.orderId });
});

Orchestration Flow

class SagaOrchestrator {
    async advance(sagaId) {
        const state = await this.store.load(sagaId);

        if (state.status === "compensating") {
            return this.continueCompensation(state);
        }

        const next = this.definition.steps[state.currentStep];

        if (!next) {
            return this.store.complete(sagaId);
        }

        const outcome = await this.dispatch(next, state.context);

        if (outcome.ok) {
            await this.store.advanceStep(sagaId, next.name);
            return this.advance(sagaId);
        }

        if (next.type === "retriable") {
            return this.store.scheduleRetry(sagaId, next.name, outcome.error);
        }

        await this.store.beginCompensation(sagaId, next.name);
        return this.continueCompensation(await this.store.load(sagaId));
    }
}

The Isolation Problem

Sagas provide no isolation. Every intermediate state is visible to concurrent readers and writers, producing anomalies that traditional transactions prevent.

Countermeasures

-- Semantic lock: the record advertises an in-progress saga
UPDATE orders
SET status      = 'payment_pending',
    saga_id     = :saga_id,
    locked_until = CURRENT_TIMESTAMP + INTERVAL '5 minutes'
WHERE order_id  = :order_id
  AND (saga_id IS NULL OR locked_until < CURRENT_TIMESTAMP);

-- Readers decide how to treat pending records
SELECT order_id, status, total
FROM orders
WHERE customer_id = :customer_id
  AND status NOT IN ('payment_pending', 'compensating');

Idempotency Is Mandatory

Every step and every compensation will be retried. Without idempotency, retries duplicate effects and compensations over-correct.

CREATE TABLE saga_step_execution (
    saga_id      VARCHAR(80) NOT NULL,
    step_name    VARCHAR(80) NOT NULL,
    attempt_key  VARCHAR(80) NOT NULL,
    status       VARCHAR(20) NOT NULL,
    result       JSONB       NULL,
    executed_at  TIMESTAMP   NOT NULL,
    PRIMARY KEY (saga_id, step_name)
);

-- Claim execution atomically; conflict means already done
INSERT INTO saga_step_execution (
    saga_id, step_name, attempt_key, status, executed_at
)
VALUES (:saga_id, :step_name, :attempt_key, 'in_progress', CURRENT_TIMESTAMP)
ON CONFLICT (saga_id, step_name) DO NOTHING
RETURNING attempt_key;

When Compensation Fails

This is the hardest case in the pattern. The forward step succeeded, the saga must abort, and the undo will not complete.

async function compensateWithEscalation(step, context, log) {
    const outcome = await retryWithBackoff(
        () => step.compensation(context),
        {
            maxAttempts: 20,
            maxDurationMs: 6 * 60 * 60 * 1000,
            isRetriable: (e) => !e.permanent
        }
    );

    if (outcome.succeeded) {
        return await log.record(context.sagaId, step.name, "compensated");
    }

    await log.record(context.sagaId, step.name, "compensation-failed", {
        attempts: outcome.attempts,
        lastError: outcome.error
    });

    await escalation.raise({
        severity: "high",
        sagaId: context.sagaId,
        step: step.name,
        message: "Compensation exhausted, manual intervention required",
        context: context.summary()
    });

    return { status: "requires-intervention" };
}

Saga State Persistence

CREATE TABLE saga_instance (
    saga_id        VARCHAR(80)  PRIMARY KEY,
    definition     VARCHAR(80)  NOT NULL,
    status         VARCHAR(30)  NOT NULL,
    current_step   VARCHAR(80)  NULL,
    context        JSONB        NOT NULL,
    started_at     TIMESTAMP    NOT NULL,
    updated_at     TIMESTAMP    NOT NULL,
    completed_at   TIMESTAMP    NULL,
    failure_reason TEXT         NULL
);

CREATE INDEX idx_saga_stuck
    ON saga_instance (status, updated_at)
    WHERE status IN ('running', 'compensating');

-- Recovery sweep for abandoned sagas
SELECT saga_id, definition, current_step, updated_at
FROM saga_instance
WHERE status IN ('running', 'compensating')
  AND updated_at < CURRENT_TIMESTAMP - INTERVAL '10 minutes'
ORDER BY updated_at;

A Worked Example

Monitoring

Verification

describe("order saga", function () {
    it("compensates all completed steps when a step fails", async function () {
        paymentService.failNext("authorize");

        const result = await saga.execute(orderContext);

        expect(result.status).toBe("compensated");
        expect(await inventory.reservationFor(orderContext.orderId)).toBeNull();
    });

    it("retries forward rather than compensating after the pivot", async function () {
        shippingService.failNext("create");

        const result = await saga.execute(orderContext);

        expect(result.status).toBe("awaiting-retry");
        expect(await payments.captured(orderContext.orderId)).toBe(true);
    });

    it("is idempotent under duplicate step execution", async function () {
        await saga.executeStep("capture-payment", orderContext);
        await saga.executeStep("capture-payment", orderContext);

        const charges = await payments.chargesFor(orderContext.orderId);
        expect(charges.length).toBe(1);
    });

    it("escalates when compensation cannot complete", async function () {
        inventoryService.failPermanently("release");
        paymentService.failNext("authorize");

        const result = await saga.execute(orderContext);

        expect(result.status).toBe("requires-intervention");
        expect(escalation.raised()).toHaveLength(1);
    });

    it("resumes correctly after orchestrator restart", async function () {
        const started = saga.execute(orderContext);
        await faultInjector.crashOrchestrator();
        await orchestrator.restart();
        await orchestrator.recoverStuckSagas();

        expect(await saga.status(orderContext.sagaId)).toBe("completed");
    });
});

Common Design Mistakes

System Design Interview Discussion

Design Checklist

Knowledge Check

Summary

A saga replaces one distributed transaction with a sequence of local transactions, each committing immediately. Atomicity is abandoned and approximated through compensating actions that semantically undo completed work.

Compensation is not rollback. It is a new business action with its own visible consequences, and some actions cannot be compensated at all. This makes step ordering critical: irreversible work must sit after the pivot, where failure means retrying forwards rather than undoing backwards.

Sagas provide no isolation, so intermediate state is visible and anomalies such as dirty reads and lost updates become possible. Semantic locks, commutative operations, and careful ordering are the practical countermeasures.

Every step and compensation will be retried, making idempotency mandatory. Saga state must be persisted before dispatching, and the hardest case — compensation that cannot complete — must be escalated rather than silently abandoned.