Saga pattern

May 10, 2026··

13 min read

Open full tree

The Saga Pattern — A Deep Dive

Abstract

The Saga pattern is an architectural and programming approach for managing long-lived, distributed transactions across multiple services in a microservices (or distributed systems) landscape. It replaces single, strongly consistent distributed transactions (e.g., 2PC) with a sequence of local transactions and compensating actions that together yield eventual consistency. This article covers the origins, concepts, theory, practical patterns (choreography vs orchestration), concrete implementations, failure modes, testing and observability, best practices, tooling, and future directions.

Table of contents

History and motivation
Core concepts and definitions
Theoretical foundations
The Saga execution model
Implementation styles: choreography vs orchestration
Practical implementation patterns and integrations
Example scenarios and code samples
Failure modes and correctness concerns
Tools, platforms, and frameworks
Testing, monitoring, and observability
Best practices and anti-patterns
Advanced topics and extensions
Future directions and research opportunities
Conclusion
References and further reading

History and motivation

Origins: The notion of a Saga was introduced by Hector Garcia-Molina and Kenneth Salem in their 1987 paper "Sagas" as an alternative to locking-based long transactions and two-phase commit. The idea addressed long-running business processes where holding locks or using strict atomic distributed transactions is impractical.
Motivation today: In microservices architectures, one business operation (e.g., place an order) often spans several autonomous services (orders, inventory, payments, shipping). Strong distributed transactions (e.g., 2PC) introduce blocking, coupling, and availability limitations. Sagas enable coordination while maintaining service autonomy and high availability, at the price of eventual consistency and added complexity for compensations.

Core concepts and definitions

Local transaction: A single ACID transaction executed within one service that updates its own state and publishes any outgoing messages/events. Local transactions must be atomic and durable within the service boundary.
Saga: A sequence of local transactions executed by multiple services, where each local transaction may have an associated compensating transaction. A saga completes if all steps succeed; otherwise compensating steps are invoked to roll back previously completed steps.
Compensation: An operation that semantically undoes or mitigates the effect of a previously executed local transaction. Compensations are not necessarily strict inverses (they may perform corrective or alternative actions).
Coordinator: Logical component (could be a service) that tracks saga state, decisions, and next steps. In choreography, there is no central coordinator; in orchestration there is.
Idempotency: Design of local transactions and compensations so they can be safely retried without producing incorrect duplicate effects.
Eventual consistency: Acceptance that the system converges to a consistent state over time rather than enforcing strong consistency during the saga.

Theoretical foundations

ACID vs BASE: Sagas embody the BASE model—Basically Available, Soft state, Eventual consistency—trading off atomicity across services for availability and scalability.
State machine model: A saga can be formalized as a state machine (or workflow) where states represent progress and compensations map to transitions that revert state.
Correctness properties:
- Atomicity (saga-level): Sagas don't provide atomicity in the traditional sense. Instead, guarantees are about forward completion or compensating actions to reach a consistent (but possibly different) state.
- Consistency: The system reaches a business-consistent state (application-specific) after saga completion or compensation.
- Isolation: Interleavings matter; sagas cannot generally provide serializable isolation across services, so business logic must tolerate concurrent updates and intermediate inconsistent states.
- Durability: Saga states and decisions must be persisted so recovery can continue across crashes.
Compensation semantics: Compensations are application-level and may be non-deterministic and non-atomic. They must be designed to be idempotent and safe to run after other actions.

The Saga execution model Primary flow:
Start saga (external request or event).
Execute step 1: a local transaction in service A. If success, continue; else run compensation chain (if needed) and finish as failed.
Execute step 2: local transaction in service B. If success, continue; else run compensation(s) for step 1, etc.
Continue until final step completes; then saga is successful.

Compensation flow:

When a step fails (or timeouts), previously completed steps must be compensated. Compensations are often executed in reverse order of the forward steps.

Saga state:

Typical lifecycle states: Started, In Progress, Completed, Failed, Compensating, Compensated.
State must be persisted reliably for recovery.

Ordering and parallel steps:

Sagas can contain sequential and parallel steps. For parallel branches, compensation ordering must be well-defined (reverse of forward completion ordering or a policy).

Implementation styles: choreography vs orchestration Two main styles for implementing sagas:

A. Choreography (Event-driven)

Each participant listens for events and decides whether to act and which event to publish next.
No central coordinator; the saga emerges from event flows (a distributed workflow).
Pros: Low coupling, simple participants, scalable.
Cons: Harder to observe, reason about, coordinate complex flows, or implement retries/timeouts; can become event spaghetti.

B. Orchestration (Central coordinator)

A central orchestrator (saga manager) sends commands to participants or instructs them via events; it tracks state and decides next steps and compensations.
Pros: Easier to control workflow, observe and debug, manage retries, and persist saga state.
Cons: Adds a single point of logic (but it can be distributed for availability), potential coupling to workflow representation.

Hybrid patterns exist where lightweight orchestration is used for complex cases, and choreography for simpler flows.

Practical implementation patterns and integrations Key patterns and integrations used with sagas:

Outbox pattern (for atomic write + publish): To avoid lost messages and achieve atomicity between local DB commit and emitted events, write event to an outbox table in the same DB transaction, and publish in a separate process.
Inbox/Idempotent consumer: Consumers deduplicate messages by keeping an inbox of processed message IDs.
Change Data Capture (CDC): Publish events via CDC for database changes (e.g., Debezium) to integrate with event streams reliably.
Exactly-once semantics: Usually implemented by idempotency + deduplication; full exactly-once across services is very hard and seldom required.
Compensation design patterns:
- Inverse operation: e.g., if step debits an account, compensation credits it back.
- Semantic compensation: apply business-specific corrective action (e.g., mark order canceled and restock items).
Timeouts and sagas with human steps: Long-running sagas can include manual approvals; orchestrator must support timers/timeouts and human interactions.
Transaction boundaries within services: Each step must be a local, atomic DB transaction; do not span steps across services.

Example scenarios and code samples

7.1 Example: e-commerce order placement (orchestration) Scenario: Place an order involves Order service, Inventory, Payment, and Shipping.

Flow:

Order service creates "ORDER_CREATED" (reserve order).
Inventory service reserves items (local tx). Emits "INVENTORY_RESERVED".
Payment service charges customer (local tx). Emits "PAYMENT_COMPLETED".
Shipping service schedules shipment (local tx). Emits "SHIPPING_SCHEDULED".
Orchestrator marks order complete.

If payment fails at step 3, orchestrator triggers compensations:

Instruct inventory to release reservation (compensating tx).
Mark order as canceled.

Pseudo orchestration (simplified):

Plain Text

orchestrator.handle(OrderCreatedEvent e):
  try:
    publish ReserveInventoryCommand(e.orderId)
    wait for InventoryReserved or InventoryReserveFailed
    publish ChargePaymentCommand(e.orderId)
    wait for PaymentSucceeded
    publish ScheduleShippingCommand(e.orderId)
    wait for ShippingScheduled
    publish CompleteOrderCommand(e.orderId)
  except AnyFailure as f:
    publish CancelOrderCommand(e.orderId)
    for each completedStep in reverse(order of completion):
      publish corresponding CompensationCommand(completedStep, e.orderId)

7.2 Choreography example (Kafka)

Order service publishes "OrderCreated".
Inventory consumes "OrderCreated", reserves stock, publishes "InventoryReserved" or "InventoryReserveFailed".
Payment consumes "InventoryReserved", attempts payment, publishes "PaymentCompleted"/"PaymentFailed".
Order service listens to "PaymentCompleted" to mark order success; listens to failures to initiate compensations by publishing "CancelOrder" (which Inventory listens to and releases stock).

7.3 AWS Step Functions (orchestration JSON snippet) Simple sequential saga:

JSON

{
  "StartAt": "ReserveInventory",
  "States": {
    "ReserveInventory": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:ReserveInventory",
      "Next": "ChargePayment",
      "Catch": [{
        "ErrorEquals": ["States.ALL"],
        "Next": "CompensateReserveInventory"
      }]
    },
    "ChargePayment": {
      "Type": "Task",
      "Resource": "...ChargePayment",
      "Next": "ScheduleShipping",
      "Catch": [{
        "ErrorEquals": ["States.ALL"],
        "Next": "CompensateReserveInventory"
      }]
    },
    "ScheduleShipping": {
      "Type": "Task",
      "Resource": "...ScheduleShipping",
      "End": true,
      "Catch": [{
        "ErrorEquals": ["States.ALL"],
        "Next": "CompensateChargePayment"
      }]
    },
    "CompensateReserveInventory": {
      "Type": "Task",
      "Resource": "...CompensateReserveInventory",
      "End": true
    },
    "CompensateChargePayment": {
      "Type": "Task",
      "Resource": "...RefundPayment",
      "Next": "CompensateReserveInventory"
    }
  }
}

7.4 Temporal (TypeScript) simplified example Temporal and Cadence provide durable orchestrators where replayable workflows coordinate activities and compensations.

Pseudo-code workflow:

TypeScript

export async function orderWorkflow(orderId: string) {
  const reserved = await callActivity('reserveInventory', orderId)
  if (!reserved) {
    return fail('inventory')
  }
  try {
    await callActivity('chargePayment', orderId)
    await callActivity('scheduleShipping', orderId)
    return success()
  } catch (err) {
    // compensations
    await callActivity('releaseInventory', orderId)
    await callActivity('refundPayment', orderId).catch(() => {/* log */})
    return failed(err)
  }
}

Failure modes and correctness concerns Common operational concerns:

Message loss, duplication, reordering.
- Mitigate: outbox pattern, durable message brokers, idempotency handling, deduplication stores.
Partial failures and network partitions:
- Sagas continue to be retried and compensations may be triggered; ensure idempotency and retry policies.
Non-idempotent compensations:
- Compensations must be idempotent or be guarded by deduplication to avoid double undo.
Side effects that can't be fully undone:
- Some effects (e.g., shipping a physical package) cannot be fully reversed. Design compensations as mitigating actions (refund, notify).
Concurrency and race conditions:
- When multiple sagas touch same resources, use optimistic concurrency control or domain-level conflict resolution.
Ordering and parallelism:
- If steps run in parallel, compensations must respect dependencies or be designed for concurrency.
Long-running sagas & resource leaks:
- Reserve resources with TTLs or separate reclamation processes; monitor and clean up stuck sagas.
Durability of saga state:
- Persist every step's success/failure and the overall saga decision to recover after crashes.
Correctness vs performance:
- Adding global locks or coordinators yields stronger correctness but reduces availability/scalability.

Tools, platforms, and frameworks Orchestration/platforms:

Temporal (and Uber Cadence): durable orchestration with workflow code, retry, timers, signals, and built-in state persistence.
AWS Step Functions: serverless state machines with native retries, error handling, and integrations.
Camunda: BPM/workflow engine for business processes, supports saga-like processes.
Netflix Conductor: microservices orchestrator for complex workflows.
Azure Durable Functions: orchestrator for serverless functions (stateful workflows).

Event-driven libraries and frameworks:

Apache Kafka (with patterns like outbox + CDC).
Debezium for CDC.
Spring Cloud and Saga helpers; microservices.io by Chris Richardson (patterns and examples).
NServiceBus, MassTransit: include saga abstractions in .NET ecosystems.

Testing, monitoring, and observability Testing:

Unit tests for individual local transactions and compensation logic.
Integration tests with in-memory or test containers for service interactions.
End-to-end tests for full saga flows, including failure injection (simulate delayed/failing services).
Property-based and model-checking testing to validate invariants.
Chaos testing to validate resilience to partial failures and network partitions.

Observability:

Distributed tracing (e.g., OpenTelemetry): propagate correlation IDs and trace across services.
Saga dashboards: track saga instances, state transitions, durations, and failures.
Metrics: number of active sagas, success rate, average duration, compensations triggered, retry counts.
Structured logging with correlation IDs and step labels.
Dead-letter queues: messages that could not be processed — ensure alerting and manual remediation.

Best practices and anti-patterns

Best practices:

Design compensations as idempotent and safe for retries.
Use the outbox pattern to ensure reliable event publication.
Persist saga state in durable storage to enable recovery.
Use correlation IDs and propagate context across services.
Keep steps small and local to a single service.
Prefer orchestration for complex multi-step flows or where observability and deterministic control matter.
Use choreography for simple, event-driven flows.
Define clear SLAs and timeouts; set up automated cleanup for stale sagas.
Document the business invariants and compensation semantics clearly.

Anti-patterns:

Trying to make sagas provide strict ACID-like semantics (instead of acknowledging eventual consistency).
Using compensations that cannot meaningfully reverse side effects.
Using long-held distributed locks in an attempt to provide cross-service isolation.
Allowing business-critical invariant checks to exist only as eventual processes without compensation strategies.
Overusing choreography to the point of event spaghetti.

Advanced topics and extensions Nested sagas:

A saga step can itself be a nested saga. Orchestration engines often model this as sub-workflows. Compensation then unwinds nested sagas appropriately.

Parallel and conditional branches:

Parallel steps require coordination of compensations in reverse completion order or via per-branch compensation plans.

Compensation policies:

Best-effort vs guaranteed compensations. You may choose retries with backoff, escalate to human compensation workflows, or compensate with alternative operations.

CRDTs & conflict-free replicated data:

For some use cases, CRDTs can reduce need for compensations by enabling convergence without explicit rollback. Sagas and CRDTs solve different problems but can complement each other.

Formal verification and model checking:

Sagas can be modeled and verified using formal methods (model checking, temporal logic) to ensure invariants and compensation coverage.

Automated compensation generation (research):

Work is ongoing to infer compensations automatically from business intent or transactional logs, but most practical systems rely on developer-defined compensations.

Future directions and research opportunities

Better developer ergonomics: richer languages/DSLs and frameworks that make writing correct compensations easier (e.g., typed sagas).
Automated compensation synthesis: AI-assisted suggestion and verification of compensations.
Integration with consensus protocols: hybrid approaches that use consensus for selective strong consistency segments.
Verification tools: model checkers and runtime verifiers to assert invariants across sagas.
Improved exactly-once and semantics: better support across broker+DB stacks using transactional messaging with less complexity.
Serverless-first saga platforms: durable workflow engines optimized for serverless microservices with pay-per-use semantics.
Observability primitives: standardization of saga tracing, schema, and dashboards.

Conclusion The Saga pattern is a pragmatic and widely applicable approach for managing distributed, long-lived business transactions in modern microservices architectures. It shifts the problem from enforcing global atomicity to managing a sequence of local transactions and compensations, emphasizing eventual consistency, resilience, and service autonomy. While sagas make systems scalable and available, they demand careful design of compensations, strong observability, durable state management, and rigorous testing. Selecting orchestration versus choreography, implementing outbox patterns, designing idempotent operations, and preparing for human-in-the-loop recovery are critical to successful saga implementations.
References and further reading

Hector Garcia-Molina and Kenneth Salem, "Sagas", 1987 (original paper introducing sagas).
Chris Richardson, "Microservices Patterns", 2018 — chapter on Saga pattern.
microservices.io — Saga pattern (patterns & anti-patterns).
Temporal documentation (https://temporal.io).
AWS Step Functions documentation — state machine examples and error handling.
"Patterns for Reliable Messaging" — outbox/inbox patterns described in messaging literature.
Articles and blog posts from architecture teams (AWS, Netflix tech blogs, etc.) on long-running transactions and workflow orchestration.

Appendix: Quick decision guide

Use Saga when:
- You have multi-service business transactions that cannot or should not use 2PC.
- You can tolerate eventual consistency.
- You can design compensating actions or mitigations.
Prefer orchestration when:
- The workflow is complex, requires clear control, retries, timers, or central monitoring.
Prefer choreography when:
- Flows are simple, teams prefer decoupling, and events are natural triggers.
Avoid sagas if:
- Many effects are irrevocable and no meaningful compensations exist.
- Strong consistency across services is mandatory for correctness.

End of article.

If you want, I can:

Provide a full, runnable Temporal or AWS Step Functions sample (service stubs + activities).
Draft a concrete saga state machine for a particular domain (e.g., travel booking).
Review a real-world saga design and point out risks and mitigations.