Repository Pattern

Overview

A repository mediates between the domain and data mapping layers. To the caller it behaves like a collection: ask for an order, change it, and put it back. The caller does not see SQL, connection handling, or ORM sessions.

How it works

The interface lives close to the domain and speaks in domain terms. The implementation sits in infrastructure.

class OrderRepository(Protocol):
    def get(self, order_id: OrderId) -> Order: ...
    def add(self, order: Order) -> None: ...

class SqlOrderRepository:
    def get(self, order_id):
        row = db.query("select * from orders where id = %s", order_id)
        return to_domain(row)

UseCase -> OrderRepository (interface) <- SqlOrderRepository -> DB
                                       <- InMemoryOrderRepository (tests)

Pair it with the unit of work to commit changes across several repositories atomically. For read-side screens, bypass the repository and use dedicated query services that return flat read models.

Pitfalls

• Returning IQueryable or ORM query builders, which leaks persistence into callers.
• Creating one generic repository with dozens of finder methods.
• One repository per table, which lets code modify aggregate internals directly.
• Putting business rules inside the repository.
• Using repositories for reporting queries where joins and projections matter.

Key takeaways

• One repository per aggregate root.
• The interface speaks the domain language.
• Use in-memory fakes in tests.
• Keep reporting queries separate from aggregate persistence.