Transaction boundaries

In this illustrative example, placing an order writes three local records: the order, a stock reservation and a dispatch request. The chosen business rule requires all three or none. If each repository commits independently, failure in the third call can leave the first two saved. Moving the calls into the same supported transaction changes that outcome.

The boundary decides what fails together#

Compare the same three writes under two policies. The snippets are pseudocode: the repositories and unit of work are application-specific, not a runnable framework API.

# Illustrative pseudocode: every repository call commits independently.
# All three operations write local database records, not remote bookings.
def place_order(cmd):
    order = orders.insert(cmd)                   # BEGIN ... COMMIT
    inventory.reserve(order.lines)              # BEGIN ... COMMIT
    dispatch.book(order.customer, order.lines)   # BEGIN ... raises

# The order and reservation remain; no local dispatch record was saved.

Each successful commit is already outside the next call’s rollback scope. No exception in the third repository can automatically undo the first repository’s earlier commit.

# Illustrative pseudocode: repositories share one database transaction.
# dispatch.book writes a LOCAL dispatch record; it makes no HTTP call.
def place_order(cmd):
    with unit_of_work() as uow:                  # BEGIN
        order = uow.orders.insert(cmd)
        uow.inventory.reserve(order.lines)
        uow.dispatch.book(order.customer, order.lines)
    # COMMIT together, or roll back this transaction's database writes.

# The unit of work owns the boundary; repositories do not commit separately.

The second version works only because every repository participates in the same database transaction and the unit of work rolls back on failure. Passing the same object name is not enough if a repository opens another connection and commits independently. A remote courier booking is not made atomic by placing it inside this block.

Find the actual commit and rollback paths before relying on the shape of the code. SQLAlchemy 2.0’s transaction documentation distinguishes a session’s tracked transaction from the connection-level transactions it uses. Its Session.begin() context commits on normal completion and rolls back on an exception. The default autobegin behaviour can establish a transaction without an explicit call to begin.

Atomicity is also not the whole concurrency story. Two transactions can both read a condition before either changes it. Constraints, locks, conditional updates or a suitable isolation level must protect the actual rule. Merely enlarging a transaction does not prove that a read-then-write decision is safe.

Relate the boundary to the business rule#

An aggregate is a modelling boundary for objects whose rules are managed together. It helps explain which changes should remain consistent; it is not a database engine’s limit on how many objects or tables one transaction can update. Do not turn a modelling preference into a universal claim that every transaction must touch exactly one aggregate.

Start with the failure you need to prevent. In the example, an order without its required reservation is invalid, so the design must prevent or explicitly reconcile that state. A reporting view that is briefly behind may be acceptable, so it can have a separate update boundary. Document the accepted intermediate state rather than assuming every disagreement is a defect.

Making the boundary too broad can make unrelated requests compete for the same resources. Making it too narrow can leave part of a required change committed. The useful question is which state is allowed after a failure and which concurrent change could invalidate the decision. Then choose the transaction and coordination mechanism that enforces that rule.

The call inside the transaction#

Now replace the local dispatch write with an HTTP booking. A handler writes an order, calls the courier and commits after the reply. Two different problems appear.

First, waiting for the courier can keep database resources held longer. For example, PostgreSQL 18’s locking documentation describes row locks normally lasting until the transaction ends, with qualifications such as savepoint rollback. A slow remote call can therefore extend contention for affected rows. This is not a universal lock duration or a claim that every database read blocks writers.

Second, the booking can succeed before the local commit fails. Rolling back the database does not cancel that external action. A timeout is ambiguous too: it does not establish that the courier did nothing. Retrying safely requires a way to recognise the same request or reconcile its outcome.

The transactional outbox pattern changes which operations must commit together. Save the order and a pending message in one local transaction. A separate worker publishes the message after commit. The interactive example below uses a broker notification rather than a courier API so that the local state, publication and consumer effect stay visible as separate steps.

Compare a crash after commit with a crash after publishing. A pending record lets a restarted worker find unfinished delivery work. It does not prove that a previous publish failed: a crash before the sent marker can cause a repeat. The outbox pattern’s documented failure window is why the receiver must handle duplicates where required. The linked guide includes a runnable SQLite example; this page’s repository snippets remain pseudocode.

An event’s meaning supplies no delivery guarantee. The next architecture topic, event delivery and consumer obligations, separates the transport contract from the reported occurrence. Idempotency keys and safe retries then explains repeated effects. Keeping the full business-event history to reconstruct state is yet another decision, covered by event sourcing, not a requirement for using an outbox.