Design Patterns, Explained Simply · Modern Patterns and Choosing Well
Repository and Unit of Work
Hide data access behind a collection-like interface, and group changes so they are saved together in one transaction.
The problem
Business logic in an orders service is full of SQL: SELECT * FROM orders WHERE customer_id = ... sits next to the discount rules. Unit tests need a real database, swapping MySQL for an API call is a rewrite, and the same query is copy-pasted in five places with small differences.
Worse, place_order() saves the order, then the order lines, then updates stock, each in its own call. When the stock update fails, the order is already saved without its stock reserved.
Real-world analogy
- Repository: a library's front desk. You ask for "books by this author" and get them; you don't walk into the stacks or learn the shelving system. The library could move to a new building and your request wouldn't change.
- Unit of Work: a shopping basket at the till. You collect items, and everything is paid for in one transaction at the end. If the card is declined, you don't leave with half the basket.
Without the pattern
def place_order(customer_id, items):
db.execute("INSERT INTO orders ...") # SQL mixed with business rules
for item in items:
db.execute("INSERT INTO order_lines ...")
db.execute("UPDATE stock SET ...") # if this fails, the order is half-saved
The pattern
Repository (from Martin Fowler's Patterns of Enterprise Application Architecture):
- An interface that looks like an in-memory collection of domain objects:
add(order),get(id),for_customer(id). - Implementations hide storage: SQL, an ORM, an HTTP API, or an in-memory list for tests.
- Business code depends on the interface (dependency inversion).
Unit of Work:
- Tracks objects that were added or changed during one business operation.
commit()writes all of them in one transaction; any failure rolls back everything.- Repositories register changes with the unit of work instead of writing immediately.
The code
class OrderRepository: # collection-like interface; in-memory for this demo
def __init__(self, uow):
self.uow, self.rows = uow, {}
def add(self, order):
self.uow.register(("order", order))
def for_customer(self, customer):
return [o for o in self.rows.values() if o["customer"] == customer]
class StockRepository:
def __init__(self, uow, stock):
self.uow, self.stock = uow, stock
def reserve(self, sku, qty):
self.uow.register(("stock", (sku, qty)))
class UnitOfWork:
def __init__(self):
self.pending = []
def register(self, change):
self.pending.append(change)
def commit(self, orders, stock):
print(" BEGIN")
try:
for kind, data in self.pending:
if kind == "order":
orders.rows[data["id"]] = data
print(f" INSERT order {data['id']}")
else:
sku, qty = data
if stock.stock[sku] < qty:
raise ValueError(f"not enough {sku}")
stock.stock[sku] -= qty
print(f" UPDATE stock {sku} -{qty}")
print(" COMMIT")
except ValueError as e:
print(f" ROLLBACK ({e})")
for kind, data in self.pending: # undo the in-memory changes
if kind == "order":
orders.rows.pop(data["id"], None)
self.pending.clear()
uow = UnitOfWork()
orders, stock = OrderRepository(uow), StockRepository(uow, {"mug": 5})
for order_id, qty in [(1, 2), (2, 9)]:
print(f"place order {order_id} ({qty} mugs)")
orders.add({"id": order_id, "customer": "ada", "sku": "mug", "qty": qty})
stock.reserve("mug", qty)
uow.commit(orders, stock)
print("ada's orders:", [o["id"] for o in orders.for_customer("ada")], "| mugs left:", stock.stock["mug"])
Output
place order 1 (2 mugs) BEGIN INSERT order 1 UPDATE stock mug -2 COMMIT place order 2 (9 mugs) BEGIN INSERT order 2 ROLLBACK (not enough mug) ada's orders: [1] | mugs left: 3
type Order = { id: number; customer: string; sku: string; qty: number };
type Change = { kind: "order"; order: Order } | { kind: "stock"; sku: string; qty: number };
class UnitOfWork {
private pending: Change[] = [];
register(change: Change) { this.pending.push(change); }
commit(orders: OrderRepository, stock: StockRepository) {
console.log(" BEGIN");
try {
for (const c of this.pending) {
if (c.kind === "order") {
orders.rows.set(c.order.id, c.order);
console.log(` INSERT order ${c.order.id}`);
} else {
if (stock.stock[c.sku] < c.qty) throw new Error(`not enough ${c.sku}`);
stock.stock[c.sku] -= c.qty;
console.log(` UPDATE stock ${c.sku} -${c.qty}`);
}
}
console.log(" COMMIT");
} catch (e) {
console.log(` ROLLBACK (${(e as Error).message})`);
for (const c of this.pending) if (c.kind === "order") orders.rows.delete(c.order.id); // undo in-memory changes
}
this.pending = [];
}
}
class OrderRepository { // collection-like interface; in-memory for this demo
rows = new Map<number, Order>();
constructor(private uow: UnitOfWork) {}
add(order: Order) { this.uow.register({ kind: "order", order }); }
forCustomer(customer: string) { return [...this.rows.values()].filter((o) => o.customer === customer); }
}
class StockRepository {
constructor(private uow: UnitOfWork, public stock: Record<string, number>) {}
reserve(sku: string, qty: number) { this.uow.register({ kind: "stock", sku, qty }); }
}
const uow = new UnitOfWork();
const orders = new OrderRepository(uow);
const stock = new StockRepository(uow, { mug: 5 });
for (const [orderId, qty] of [[1, 2], [2, 9]]) {
console.log(`place order ${orderId} (${qty} mugs)`);
orders.add({ id: orderId, customer: "ada", sku: "mug", qty });
stock.reserve("mug", qty);
uow.commit(orders, stock);
}
console.log(`ada's orders: [${orders.forCustomer("ada").map((o) => o.id).join(", ")}] | mugs left: ${stock.stock.mug}`);
Output
place order 1 (2 mugs) BEGIN INSERT order 1 UPDATE stock mug -2 COMMIT place order 2 (9 mugs) BEGIN INSERT order 2 ROLLBACK (not enough mug) ada's orders: [1] | mugs left: 3
import java.util.ArrayList;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
public class Main {
public static void main(String[] args) {
UnitOfWork uow = new UnitOfWork();
OrderRepository orders = new OrderRepository(uow);
StockRepository stock = new StockRepository(uow, new HashMap<>(Map.of("mug", 5)));
for (int[] o : new int[][]{{1, 2}, {2, 9}}) {
System.out.println("place order " + o[0] + " (" + o[1] + " mugs)");
orders.add(new Order(o[0], "ada", "mug", o[1]));
stock.reserve("mug", o[1]);
uow.commit(orders, stock);
}
System.out.println("ada's orders: " + orders.forCustomer("ada").stream().map(Order::id).toList()
+ " | mugs left: " + stock.stock.get("mug"));
}
}
record Order(int id, String customer, String sku, int qty) {}
class UnitOfWork {
private final List<Object> pending = new ArrayList<>(); // Order or String[]{sku, qty}
void register(Object change) { pending.add(change); }
void commit(OrderRepository orders, StockRepository stock) {
System.out.println(" BEGIN");
try {
for (Object c : pending) {
if (c instanceof Order order) {
orders.rows.put(order.id(), order);
System.out.println(" INSERT order " + order.id());
} else if (c instanceof String[] s) {
int qty = Integer.parseInt(s[1]);
if (stock.stock.get(s[0]) < qty) throw new IllegalStateException("not enough " + s[0]);
stock.stock.merge(s[0], -qty, Integer::sum);
System.out.println(" UPDATE stock " + s[0] + " -" + qty);
}
}
System.out.println(" COMMIT");
} catch (IllegalStateException e) {
System.out.println(" ROLLBACK (" + e.getMessage() + ")");
for (Object c : pending) if (c instanceof Order order) orders.rows.remove(order.id()); // undo in-memory changes
}
pending.clear();
}
}
class OrderRepository { // collection-like interface; in-memory for this demo
final Map<Integer, Order> rows = new LinkedHashMap<>();
private final UnitOfWork uow;
OrderRepository(UnitOfWork uow) { this.uow = uow; }
void add(Order order) { uow.register(order); }
List<Order> forCustomer(String customer) { return rows.values().stream().filter(o -> o.customer().equals(customer)).toList(); }
}
class StockRepository {
final Map<String, Integer> stock;
private final UnitOfWork uow;
StockRepository(UnitOfWork uow, Map<String, Integer> stock) { this.uow = uow; this.stock = stock; }
void reserve(String sku, int qty) { uow.register(new String[]{sku, String.valueOf(qty)}); }
}
Output
place order 1 (2 mugs) BEGIN INSERT order 1 UPDATE stock mug -2 COMMIT place order 2 (9 mugs) BEGIN INSERT order 2 ROLLBACK (not enough mug) ada's orders: [1] | mugs left: 3
Run this on your computer — see “Get Started” for setup.
<?php
class UnitOfWork {
private array $pending = [];
public function register(array $change): void { $this->pending[] = $change; }
public function commit(OrderRepository $orders, StockRepository $stock): void {
echo " BEGIN\n";
try {
foreach ($this->pending as [$kind, $data]) {
if ($kind === "order") {
$orders->rows[$data["id"]] = $data;
echo " INSERT order {$data['id']}\n";
} else {
[$sku, $qty] = $data;
if ($stock->stock[$sku] < $qty) throw new RuntimeException("not enough $sku");
$stock->stock[$sku] -= $qty;
echo " UPDATE stock $sku -$qty\n";
}
}
echo " COMMIT\n";
} catch (RuntimeException $e) {
echo " ROLLBACK ({$e->getMessage()})\n";
foreach ($this->pending as [$kind, $data]) if ($kind === "order") unset($orders->rows[$data["id"]]); // undo in-memory changes
}
$this->pending = [];
}
}
class OrderRepository { // collection-like interface; in-memory for this demo
public array $rows = [];
public function __construct(private UnitOfWork $uow) {}
public function add(array $order): void { $this->uow->register(["order", $order]); }
public function forCustomer(string $customer): array {
return array_values(array_filter($this->rows, fn($o) => $o["customer"] === $customer));
}
}
class StockRepository {
public function __construct(private UnitOfWork $uow, public array $stock) {}
public function reserve(string $sku, int $qty): void { $this->uow->register(["stock", [$sku, $qty]]); }
}
$uow = new UnitOfWork();
$orders = new OrderRepository($uow);
$stock = new StockRepository($uow, ["mug" => 5]);
foreach ([[1, 2], [2, 9]] as [$orderId, $qty]) {
echo "place order $orderId ($qty mugs)\n";
$orders->add(["id" => $orderId, "customer" => "ada", "sku" => "mug", "qty" => $qty]);
$stock->reserve("mug", $qty);
$uow->commit($orders, $stock);
}
$ids = implode(", ", array_map(fn($o) => $o["id"], $orders->forCustomer("ada")));
echo "ada's orders: [$ids] | mugs left: {$stock->stock['mug']}\n";
Output
place order 1 (2 mugs) BEGIN INSERT order 1 UPDATE stock mug -2 COMMIT place order 2 (9 mugs) BEGIN INSERT order 2 ROLLBACK (not enough mug) ada's orders: [1] | mugs left: 3
Order 2 needed 9 mugs but only 3 were left, so its order insert was rolled back too. In a real app, commit() maps to a database transaction, and the business code never sees SQL.
When to use it
- Business logic is mixed with queries, and you want it testable with an in-memory repository.
- One business operation changes several objects that must be saved together or not at all.
- You want a clear boundary between the domain and the storage technology (Domain-Driven Design, hexagonal/clean architecture).
When not to use it
- Simple CRUD apps. An ORM like Eloquent, Django ORM or Active Record already gives you query methods, and wrapping it in repositories adds a layer that mostly forwards calls.
- Generic repositories (
Repository<T>withget_all(),find_by(any_field)) that just mirror the ORM give little value. Make repository methods domain-specific (overdue_invoices()). - Hiding the database completely can hide performance problems (N+1 queries, missing indexes).
You've already used it
- ORMs as Unit of Work: SQLAlchemy's
Session, Hibernate/JPA'sEntityManagerand Doctrine'sEntityManagertrack changes and flush them in one transaction. - Spring Data repositories (
interface OrderRepository extends JpaRepository<Order, Long>). - Entity Framework:
DbContextis a unit of work; eachDbSetis repository-like.
Key points
- Repository: a collection-like interface that hides storage; business code depends on it, tests use in-memory versions.
- Unit of Work: tracks changes in one operation and commits them in one transaction.
- Most ORMs already implement Unit of Work; add repositories when they buy testability or a clear domain boundary.
- Further reading: Martin Fowler's Repository and Unit of Work.
Practice questions
What is the Repository pattern and what problem does it solve?
Answer
A collection-like interface (add, get, for_customer) that hides how domain objects are stored. Business logic no longer contains queries, can be tested with an in-memory implementation, and doesn't change if storage changes.
What does a Unit of Work do?
Answer
It tracks the objects added, changed or removed during one business operation and writes them all in one transaction on commit(), rolling everything back if any step fails.
Name an ORM feature that is a Unit of Work.
Answer
SQLAlchemy's Session, JPA/Hibernate's EntityManager, Doctrine's EntityManager and Entity Framework's DbContext all track changes and flush them together in a transaction.
When is adding repositories on top of an ORM not worth it?
Answer
In simple CRUD apps, or when the repository is a generic wrapper that just forwards every ORM call. Repositories pay off when they expose domain-specific methods and give business logic a testable boundary.
Open in the app to mark lessons complete, take notes and track your progress.