Saga pattern

API Design

Meaning

The Saga pattern manages data consistency across distributed services by sequencing local transactions, each paired with a compensating action that undoes its effect on failure. It addresses the impossibility of using traditional ACID transactions or two-phase commit across microservices with independent databases. Engineers reach for it when a business workflow spans multiple services and must remain reliable despite partial failures.

Primary Function

Distributed transaction management

Communicative Purpose

Enables long-running, multi-service business workflows to maintain eventual consistency without distributed locks or two-phase commit.

Pattern

define saga steps → execute sequentially → invoke compensating action for each completed step on failure

Função primária

Distributed transaction management

Propósito comunicativo

Enables long-running, multi-service business workflows to maintain eventual consistency without distributed locks or two-phase commit.

Situações de gatilho

Microservices: coordinating a multi-step order process (reserve inventory → charge payment → ship) across separate services; Distributed systems: replacing a monolithic transaction that no longer fits after service decomposition; Event-driven architecture: chaining compensating actions when an intermediate step fails

Contextos

Microservices architectures, event-driven systems, distributed transaction processing, CQRS + Event Sourcing stacks

Padrão

define saga steps → execute sequentially → invoke compensating action for each completed step on failure

Colocados típicos

compensating transaction
choreography vs orchestration
event bus
saga log
idempotent operations
eventual consistency

Substituições comuns

Two-phase commit (2PC): simpler but blocks and does not scale across services
Eventual consistency without saga: risks orphaned partial states with no rollback path
Distributed transaction coordinator (XA): requires homogeneous infrastructure and tight coupling

Erros comuns

Forgetting idempotency on each step: retries cause duplicate charges or duplicate shipments → business-level data corruption; Treating saga steps as atomic: assuming a single step cannot partially fail → inconsistent state when network drops mid-write; Skipping compensating action design: only designing the happy path → no recovery when step 3 of 5 fails; Mixing choreography and orchestration in one saga: unclear ownership of failure handling → debugging nightmares; Ignoring saga versioning: deploying a new step while old sagas are in flight → stuck instances

Similar / contraste

Two-phase commit: synchronous locking protocol vs asynchronous compensating actions; Workflow engine (Temporal, Camunda): external orchestrator vs in-service saga logic; Unit of Work pattern: in-process transaction boundary vs cross-service coordination

Interferências

Coming from monolithic databases: may assume a single ACID transaction can wrap all steps — distributed services have no shared transaction manager; Coming from message queue systems: may treat events as fire-and-forget — saga steps require explicit compensation semantics

Família do chunk

Two-phase commit
compensating transaction
event-driven choreography
orchestration pattern
eventual consistency

Nuance

Use only when business transactions genuinely span service boundaries — within a single bounded context, a local database transaction is simpler and faster. Performance overhead comes from the sequential nature and the need to persist saga state; parallel branches require careful merge logic. Boundary condition: sagas cannot provide isolation between concurrent instances of the same workflow without additional locking on aggregate IDs.

Efeito pragmático

Allows teams to decompose monoliths into independently deployable services while still delivering reliable multi-step business processes, at the cost of eventual consistency and added complexity in failure handling.

Dica de memória

Saga pattern: like a chain of dominoes where each piece knows how to un-tip itself — if the chain breaks midway, every fallen domino reverses in reverse order.

Upgrade path

Temporal workflow orchestration, or event-sourced CQRS saga with replayable event log

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Long-term

Examples

on OrderPlaced: inventory_service.reserve(order_id, items) on InventoryReserved: payment_service.charge(order_id, amount) on PaymentCharged: shipping_service.schedule(order_id, address) on PaymentFailed: inventory_service.release(order_id, items) on ShippingFailed: payment_service.refund(order_id, amount) inventory_service.release(order_id, items)

class OrderSaga: def run(self, order): try: self.inventory.reserve(order) self.payment.charge(order) self.shipping.schedule(order) except InventoryError: raise SagaAborted("inventory unavailable") except PaymentError: self.inventory.release(order) raise SagaAborted("payment declined") except ShippingError: self.payment.refund(order) self.inventory.release(order) raise SagaAborted("shipping failed")

class SagaState: saga_id: str completed_steps: list[str] status: str # "running", "compensating", "completed" def resume_saga(saga_id): state = saga_log.load(saga_id) if state.status == "compensating": for step in reversed(state.completed_steps): invoke_compensation(step, saga_id) saga_log.mark_failed(saga_id) elif state.status == "running": next_step = determine_next_step(state) execute_step(next_step, saga_id)