Unit of Work

Overview

Martin Fowler describes a unit of work as maintaining a list of objects affected by a business transaction and coordinating the writing out of changes. Most ORMs, such as Hibernate sessions, Entity Framework contexts, and SQLAlchemy sessions, implement it internally.

How it works

The application service opens a unit, loads aggregates through repositories, calls domain methods, and commits.

with uow:                       # begins transaction
    order = uow.orders.get(order_id)
    order.confirm()
    uow.stock.reserve(order.lines)
    uow.commit()                # flush all changes atomically
# exiting without commit rolls back

begin -> load -> mutate -> commit  (all writes in one DB transaction)
                    \-> error -> rollback

Domain events raised by aggregates can be collected by the unit and dispatched only after a successful commit, or written to an outbox table in the same transaction.

Pitfalls

• Making a network call to another service inside the unit; if it hangs, locks stay held.
• Scoping the unit to the whole HTTP session or user conversation.
• Assuming it gives atomicity across a database and a message broker; use the outbox pattern for that.
• Calling commit inside repositories, which defeats the pattern.
• Not handling optimistic concurrency exceptions with a retry strategy.

Key takeaways

• One unit of work per use case, committed once.
• Keep it short and local to a single database.
• Collect events and publish after commit.
• For cross-service consistency use sagas, not larger units.