DocTreeDocTree

A learning path ready to make your own.

Saga pattern

Overview Saga pattern is an approach for managing long-lived, distributed transactions across multiple services by composing a sequence of local ACID transactions plus compensating actions to achieve eventual consistency. It replaces blocking, strongly-consistent distributed transactions (e.g., 2PC) with service autonomy, higher availability, and added compensation complexity. Why use Sagas Solves multi-service business flows (orders, inventory, payments, shipping) where 2PC is impractical. Trades global atomicity for availability and scalability (BASE: Eventually consistent). Suited when you can define compensations or mitigations for failed steps. Core concepts Local transaction: an atomic, durable operation inside one service that may publish events. Saga: a sequence of local transactions; completes if all succeed, otherwise runs compensations for prior steps. Compensation: application-level undo/mitigation (not necessarily strict inverse) and must be idempotent when possible. Coordinator: optional component that tracks saga state—present in orchestration, absent in choreography. Idempotency and durable saga state are essential for correct recovery and retries. Execution model Forward flow: start → step1 (local tx) → step2 → … → final step → success. On failure: run compensations (typically in reverse order) to return to a consistent business state. Lifecycle states: Started, In Progress, Compensating, Compensated, Completed, Failed. Supports sequential and parallel steps; parallel branches require explicit compensation ordering or policy. Implementation styles Choreography — event-driven, no central coordinator: low coupling and scalable but harder to observe and reason about; can lead to "event spaghetti". Orchestration — central saga manager: easier control, persistence, retries and observability; adds a coordination component (can be distributed for availability). Hybrid approaches combine both: use orchestration for complex flows and choreography for simple ones. Practical patterns Outbox pattern — atomically write events to an outbox table in the same DB transaction and publish them asynchronously. Inbox / idempotent consumer — deduplicate messages by tracking processed IDs. CDC (e.g., Debezium) — publish DB changes reliably into event streams. Design compensations as idempotent or guarded by deduplication; manage timeouts and human steps with timers and escalation. Common example (e-commerce) Steps: create order → reserve inventory → charge payment → schedule shipping → complete order. If payment fails, orchestrator or event-driven flow triggers inventory release and order cancellation as compensations. Implementations: orchestration via Temporal/AWS Step Functions, choreography via Kafka topics with consumer events. Failure modes & correctness concerns Message loss, duplication, reordering — mitigate with outbox, durable brokers, idempotency and dedup stores. Non-idempotent compensations and irrevocable side effects (e.g., shipped packages) require mitigation strategies (refunds, notifications) and possibly human intervention. Concurrency & race conditions — use optimistic concurrency or domain conflict resolution; ensure durable saga state for recovery. Long-running sagas risk resource leaks — use TTLs, reclamation processes and monitoring. Tools & frameworks Orchestrators: Temporal (Cadence), AWS Step Functions, Camunda, Netflix Conductor, Azure Durable Functions. Event platforms & integrations: Apache Kafka, Debezium (CDC), outbox/inbox libraries, Spring Cloud, NServiceBus, MassTransit. Testing, monitoring & observability Testing: unit tests for local tx/compensations, integration and end-to-end tests with failure injection, property-based or model-checking where appropriate, chaos testing. Observability: distributed tracing (OpenTelemetry), saga dashboards, metrics (active sagas, durations, compensation counts), structured logging with correlation IDs, dead-letter queues and alerts. Best practices & anti-patterns Best practices: design idempotent compensations, use outbox, persist saga state, propagate correlation IDs, keep steps local, choose orchestration for complex flows, set SLAs/timeouts and cleanup policies. Anti-patterns: attempt to force global ACID semantics, use irrecoverable compensations, rely on long-held distributed locks, overuse choreography for complex flows (event spaghetti). Advanced topics Nested sagas and sub-workflows; parallel and conditional branches with coordinated compensation. Compensation policies: best-effort retries, escalation to humans, or alternative mitigations. CRDTs can complement sagas by enabling convergence without explicit compensation in some domains. Formal verification, model checking and research on automated compensation synthesis and richer DSLs for safer sagas. Future directions Richer developer ergonomics and typed/DSL-based sagas; AI-assisted compensation generation and verification. Hybrid consistency models that selectively use consensus; better transactional messaging yielding simpler exactly-once semantics. Serverless-first durable workflow platforms and standardized observability primitives for sagas. Decision guide (quick) Use Sagas when multi-service transactions cannot use 2PC and eventual consistency is acceptable. Prefer orchestration for complex workflows needing centralized control, retries and observability. Prefer choreography for simple, naturally event-driven flows and low coupling. Avoid sagas when effects are irrevocable or strong cross-service consistency is mandatory. Conclusion The Saga pattern is a pragmatic approach for distributed business transactions: it enables scalable, available microservice architectures by coordinating local transactions and compensations. Successful adoption requires careful compensation design, durable state, strong observability, idempotency, and rigorous testing to manage the complexity of eventual consistency.
Open full tree
Saga patternIntroduction to Saga PatternCore Concepts of SagaImplementing Saga PatternPractical ApplicationsAdvanced Topics

Let the lesson walk with you.

Podcast

Saga pattern podcast

0:00-3:39

Follow the trail that experts already trust.

Resources

Turn quick sparks into lasting recall.

Flashcards

Saga pattern flashcards

16 cards

Question

Click to flip
Answer

Prove the idea before it slips away.

Quizzes

Saga pattern quiz

12 questions

Who introduced the Saga concept and in which year (original paper)?

Read deeper, connect wider, own the subject.

Deep Article

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

  1. History and motivation
  2. Core concepts and definitions
  3. Theoretical foundations
  4. The Saga execution model
  5. Implementation styles: choreography vs orchestration
  6. Practical implementation patterns and integrations
  7. Example scenarios and code samples
  8. Failure modes and correctness concerns
  9. Tools, platforms, and frameworks
  10. Testing, monitoring, and observability
  11. Best practices and anti-patterns
  12. Advanced topics and extensions
  13. Future directions and research opportunities
  14. Conclusion
  15. References and further reading
  1. 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.
  1. 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.
  1. 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.
  1. The Saga execution model

Primary flow:

  1. Start saga (external request or event).
  2. Execute step 1: a local transaction in service A. If success, continue; else run compensation chain (if needed) and finish as failed.
  3. Execute step 2: local transaction in service B. If success, continue; else run compensation(s) for step 1, etc.
  4. 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).
  1. 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.

  1. 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.
  1. 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:

  1. Order service creates "ORDER_CREATED" (reserve order).
  2. Inventory service reserves items (local tx). Emits "INVENTORY_RESERVED".
  3. Payment service charges customer (local tx). Emits "PAYMENT_COMPLETED".
  4. Shipping service schedules shipment (local tx). Emits "SHIPPING_SCHEDULED".
  5. 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): `` 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: `` { "StartAt": "ReserveInventory", "States": ...

Ready to see the full tree?

Clone the preview to open the complete learning structure, practice tools, and generated study materials.