Saga Pattern (Choreography & Orchestration)

Distributed transactions across microservices using compensating actions

⏱ 18 min📊 Diagram

When a single business operation spans multiple services (e.g., place order → reserve stock → charge payment → send confirmation), you can't use a traditional ACID database transaction across service boundaries. The Saga pattern solves this with a sequence of local transactions and compensating actions.

Key Concepts

Choreography-based Saga

No central coordinator. Each service publishes events and reacts to other services' events. Services are fully autonomous — Order Service publishes 'OrderCreated', Stock Service listens and publishes 'StockReserved'.

Orchestration-based Saga

A central Saga Orchestrator (Temporal, AWS Step Functions) calls each service in sequence. The orchestrator knows the full workflow and triggers compensating actions on failure.

Compensating Transactions

When step N fails, steps N-1 through 1 must be reversed. Compensation is not a rollback — it's a new forward action that semantically undoes a previous action (e.g., 'Release Reserved Stock').

Saga Choreography: Forward & Compensating Flow

Saga Orchestration: Centralized Controller

Choreography vs Orchestration

Pattern	How it Works	Pros	Cons
Choreography	Services publish and listen to events without a central controller.	Loose coupling, no single point of failure, easy to add new listeners.	Hard to track the whole flow. Cyclic dependencies can occur. Difficult to debug.
Orchestration	A central controller (e.g. Temporal, Step Functions) commands each service.	Clear workflow definition. Easy to handle timeouts and retries. Centralized status.	Orchestrator becomes a single point of failure and bottleneck. Higher coupling.

The Outbox Pattern (Crucial for Sagas)

In the code example below, if the database commits successfully but the `eventBus.publish` fails (e.g., Kafka is down), the system is in an inconsistent state. The **Transactional Outbox Pattern** solves this. Instead of directly publishing the event, you write the event to an `outbox` table in the SAME local database transaction. A separate background worker then reads the outbox table and publishes the events reliably.

Choreography Saga — Order Flow with Failure

Order Service: Creates order → publishes `OrderCreated` event
Stock Service: Consumes `OrderCreated` → reserves inventory → publishes `StockReserved`
Payment Service: Consumes `StockReserved` → charges card → if fails, publishes `PaymentFailed`
Stock Service: Consumes `PaymentFailed` → releases reserved inventory → publishes `StockReleased`
Order Service: Consumes `StockReleased` → marks order as CANCELLED

NestJS Saga Event Handler Example

stock.service.tstypescript
@EventPattern('OrderCreated')
async handleOrderCreated(@Payload() event: OrderCreatedEvent) {
  const session = await this.db.startSession();
  try {
    // Local transaction — atomic within this service
    await this.inventoryRepo.reserveStock(event.items, { session });
    
    // Publish next event only after local TX commits
    await this.eventBus.publish(new StockReservedEvent({
      orderId: event.orderId,
      reservationId: uuid(),
    }));
    await session.commitTransaction();
  } catch (err) {
    await session.abortTransaction();
    // Trigger compensating action
    await this.eventBus.publish(new StockReservationFailedEvent({
      orderId: event.orderId,
      reason: err.message,
    }));
  }
}

💡

Senior Architect Insight: Choreography works great for simple linear flows (A → B → C). Use Orchestration (Temporal.io) when flows have branching logic, parallel steps, or timeouts — the explicit workflow definition makes debugging distributed failures dramatically easier.

PreviousDatabase per Service Pattern

Next LessonB-Tree Index Internals