database-transactions

name	database-transactions
description	Define transaction boundaries, locking, and consistency guarantees for multi-step writes. Use when designing atomic operations, retries, idempotency, or concurrent write behavior.
metadata	{"triggers":{"keywords":["transaction","consistency","idempotency","lock","concurrent write"]}}

Database Transactions

Priority: P0 (CRITICAL)

One business action should have one clear consistency strategy.

Rules

• Define the unit of work before choosing transaction scope.
• Keep transaction bodies short and purposeful.
• Record isolation, lock, retry, and idempotency expectations for contested writes.
• Split eventually consistent workflows from truly atomic ones.

Verify

• Transaction boundary matches one business action.
• Isolation or locking tradeoff is explicit.
• Retry and idempotency behavior is defined for duplicate or concurrent requests.
• External side effects are not hidden inside a DB transaction without compensation.

Anti-Patterns

• No giant transaction scripts: long units increase contention and failure blast radius.
• No retry without idempotency: duplicate writes become correctness bugs.
• No mixed atomicity story: define what is immediate vs eventual.

References

• Framework Map
• Isolation Levels