Saga Pattern in NestJS: Distributed Transactions Without 2PC

The moment a checkout flow touches three services, an orders service, a payments service, and an inventory service, a single database transaction stops being an option. Each service owns its own database, so there is no shared connection to wrap in a BEGIN and COMMIT. Two-phase commit promises atomicity across nodes, but it does so by holding locks across the network while every participant waits for a coordinator to say go, and that coordinator becoming unavailable mid-vote can leave every participant blocked indefinitely.

The saga pattern solves the same problem with a different trade-off. Instead of one atomic transaction, a saga is a sequence of local transactions, each one committed immediately in its own service, with a compensating action defined for every step in case a later step fails. This article walks through implementing sagas in NestJS with the official CQRS module, comparing orchestration and choreography, and the idempotency rules that keep compensations safe when messages get redelivered.

Why two-phase commit falls apart in microservices

Two-phase commit (2PC) works well inside a single database cluster because the coordinator and participants share fast, reliable connections and a common failure domain. Spread across independently deployed services with independent databases, three problems show up quickly.

• Blocking: if the coordinator crashes after participants vote yes but before it sends the commit message, every participant holds its locks until the coordinator recovers, freezing unrelated requests that touch the same rows.
• Coupling: every service in the transaction must support the same protocol and be reachable synchronously at the same moment, which defeats the point of deploying services independently.
• Availability: 2PC trades availability for consistency in a way that does not match how most product teams want their checkout or signup flow to behave under partial outages.

Orchestration vs choreography

There are two ways to structure a saga's control flow. In choreography, each service listens for events published by other services and decides for itself what to do next, with no central coordinator. In orchestration, a single orchestrator component holds the sequence of steps and their compensations, issuing a command to each service in turn and reacting to the result. Both are valid; the right choice depends on how many services participate and how much visibility the team needs into the flow.

Implementing an orchestrated saga with NestJS CQRS

NestJS ships a CQRS module with a Saga decorator built for exactly this use case. A saga method receives an observable stream of every event dispatched through the event bus, filters it down with the ofType operator, and maps a matching event to a new command that the command bus dispatches automatically. This keeps the orchestration logic declarative: react to an event, emit the next command, or emit a compensating command when something upstream reports failure.

// order-saga.ts
import { ICommand, ofType, Saga } from '@nestjs/cqrs'
import { Injectable } from '@nestjs/common'
import { Observable } from 'rxjs'
import { map } from 'rxjs/operators'
import { OrderCreatedEvent } from './events/order-created.event'
import { ReserveInventoryCommand } from './commands/reserve-inventory.command'
import { InventoryReservationFailedEvent } from './events/inventory-reservation-failed.event'
import { CancelOrderCommand } from './commands/cancel-order.command'

@Injectable()
export class OrderSaga {
  @Saga()
  orderCreated = (events$: Observable<ICommand>): Observable<ICommand> => {
    return events$.pipe(
      ofType(OrderCreatedEvent),
      map((event) => new ReserveInventoryCommand(event.orderId, event.items)),
    )
  }

  // Compensating step: undo the order if a downstream step fails
  @Saga()
  inventoryReservationFailed = (events$: Observable<ICommand>): Observable<ICommand> => {
    return events$.pipe(
      ofType(InventoryReservationFailedEvent),
      map((event) => new CancelOrderCommand(event.orderId, event.reason)),
    )
  }
}

Each command handler in the chain performs one local transaction and either publishes a success event that the saga reacts to next, or a failure event that triggers the matching compensation. The orchestrator itself, the OrderSaga class, never talks to another service's database directly. It only knows the shape of events coming in and commands going out, which keeps it testable without spinning up every downstream service.

Designing compensating actions correctly

A compensating action is not just the reverse of the forward action; it has to reverse the business effect while accounting for anything that happened in between. Four rules keep compensations reliable in practice.

1. Compensations must be semantically opposite, not just structurally opposite: cancelling a reservation is not the same as deleting the reservation record if downstream services already read its existence to make their own decisions.
2. Compensations must be retriable, since the message that triggers a compensation can be redelivered after a network partition, a consumer restart, or an at-least-once delivery guarantee firing twice.
3. Compensations must tolerate the forward step never having happened, because the failure that triggers compensation can arrive before the forward step's own success event does, depending on message ordering.
4. Compensations must be recorded, not silently retried forever, so an operator can see which sagas are stuck in a partially compensated state and intervene manually if automated retries are exhausted.

// cancel-order.handler.ts
@CommandHandler(CancelOrderCommand)
export class CancelOrderHandler implements ICommandHandler<CancelOrderCommand> {
  constructor(
    private readonly orders: OrderRepository,
    private readonly ledger: ProcessedStepLedger, // dedupe table keyed by (sagaId, step)
  ) {}

  async execute(command: CancelOrderCommand): Promise<void> {
    const { orderId, reason } = command

    // Idempotency check — a redelivered event must not double-compensate
    const alreadyHandled = await this.ledger.wasProcessed(orderId, 'cancel-order')
    if (alreadyHandled) return

    const order = await this.orders.findById(orderId)
    if (order.status === 'cancelled') return // already terminal, safe no-op

    order.cancel(reason)
    await this.orders.save(order)
    await this.ledger.markProcessed(orderId, 'cancel-order')
  }
}

Idempotency: the property that makes retries safe

Message brokers overwhelmingly favor at-least-once delivery over exactly-once, because exactly-once delivery across a network partition is not actually achievable without cooperation from the receiver. That means every command handler in a saga, forward step or compensation, will eventually be invoked twice for the same logical event. The fix is not deduplication at the broker; it is designing each handler so that applying it twice produces the same end state as applying it once.

• Check the entity's current state before acting: if an order is already in the cancelled state, a second CancelOrderCommand should be a no-op, not a second cancellation side effect.
• Track processed step identifiers in a small ledger table keyed by saga id and step name, and skip execution when a matching row already exists.
• Make side effects like sending a confirmation email conditional on a first-time flag from the ledger check, not on the command simply arriving, since arrival does not imply novelty.

When to reach for a saga at all

Sagas add real operational cost: more event types, a ledger table for idempotency, and a mental model that spans services instead of living in one function. They earn that cost when a business process genuinely spans service boundaries and needs eventual consistency with a defined recovery path, like order fulfillment touching payments, inventory, and shipping. They are the wrong tool when the data actually belongs in one service; the fix there is usually consolidating ownership, not adding a saga on top of a bad boundary.