Repository Pattern
A repository presents collection-like access to domain objects, hiding persistence details and letting the domain stay independent of the database.
Definition
The repository pattern mediates between the domain and data mapping layers, exposing an in-memory collection interface for retrieving and storing aggregates while encapsulating query and persistence logic.
Context and scope
It is applied in layered and domain-driven designs where the domain should not depend on SQL or an ORM session.
Common misconceptions
- a repository is the same as a data access object
- repositories must expose a query builder to be useful
Anti-patterns
- returning ORM entities directly into the domain layer
- creating one repository per table instead of per aggregate
Related concepts
Authoritative source
Definition
The repository pattern mediates between the domain and data mapping layers, exposing an in-memory collection interface for retrieving and storing aggregates while encapsulating query and persistence logic.
It is applied in layered and domain-driven designs where the domain should not depend on SQL or an ORM session. Compared to simpler alternatives, this concept fits best when the trade-off it represents is the one the system actually cares about.
When to use it
A common use case is applying it at the boundary where the cost of getting it wrong is highest, and the scenario usually involves a concrete guarantee the system must uphold. Unlike an ad hoc approach, it makes that guarantee explicit, reviewable, and testable.
How it works
By returning domain objects rather than rows or ORM proxies, the repository keeps persistence ignorance, so the domain layer has no compile-time dependency on the database.
Repositories should be defined per aggregate, not per table, because the aggregate is the unit of consistency the domain cares about.
Trade-offs and alternatives
Leaking a query or criteria object through the interface turns the repository back into a data access object and gives callers control over persistence specifics. The main drawback is the extra complexity it introduces, so the benefit should clearly outweigh that cost before a team adopts it.
Common misconceptions
A persistent misconception is that a repository is the same as a data access object. Another is that repositories must expose a query builder to be useful. For example, an engineer who assumes otherwise may design around a guarantee that does not actually exist, which only becomes obvious under load or failure.
Anti-patterns to avoid
Two recurring anti-patterns are to returning ORM entities directly into the domain layer and to creating one repository per table instead of per aggregate. Both tend to surface as hard-to-debug production issues rather than obvious test failures. Related concepts include Unit of Work, Publish-Subscribe Messaging, Message Broker.