distributed-transactions

Distributed Transactions

Use this skill when one business operation spans services, databases, brokers, or external systems and cannot rely on one local ACID transaction.

Non-Negotiables

• Prefer one local ACID transaction when the data can remain inside one ownership boundary.
• Never implement a database write followed by direct message publication as an unprotected dual write.
• Assume messages can be delayed, duplicated, reordered, and redelivered.
• Make externally visible commands and consumers idempotent at the business-effect boundary.
• Acknowledging or committing a message is not proof that the business effect occurred exactly once.
• Compensation is a new business action, not a database rollback. It can fail and may require human resolution.
• Persist workflow state, deadlines, attempts, and decisions durably. Do not keep authoritative Saga state only in process memory.
• Bound retries and timeouts; quarantine poison messages and expose reconciliation paths.

Choose the Simplest Correct Pattern

1. One service and one database: use a local transaction.
2. Publish an event after a local state change: use Transactional Outbox.
3. Protect a consumer from duplicate business effects: use Inbox/deduplication, a domain idempotency key, or both.
4. A short cross-service flow with clear central ownership and complex compensation: prefer Saga orchestration.
5. A loosely coupled event reaction with few participants and no central workflow state: choreography may fit.
6. Many ordered steps, long waits, approvals, deadlines, or operational intervention: use a durable workflow engine or explicit orchestrator.
7. Strong global atomicity is genuinely mandatory: reconsider service/data boundaries before reaching for distributed locking or two-phase commit.

Design Workflow

Before proposing implementation, document:

• business invariant and consistency boundary;
• participating services and data owners;
• commands, events, correlation ID, causation ID, aggregate ID, and idempotency keys;
• state machine, terminal states, deadlines, retry policy, and concurrency policy;
• compensation for each completed step and what cannot be compensated;
• message ordering requirements and partition/routing key;
• duplicate, stale, late, and out-of-order handling;
• operator visibility, reconciliation query, replay policy, and manual-resolution path;
• schema/version evolution and deployment compatibility;
• retention and cleanup for Outbox, Inbox, workflow, and audit records.