Database

Apply the Repository Pattern Without Hiding Query Behavior

Use repositories to express persistence needs while keeping query performance and transaction boundaries visible.

A repository can provide a useful boundary between application logic and persistence. It becomes harmful when it hides important query behavior behind generic methods or imitates an in-memory collection.

Define repositories around aggregates or use cases

Methods should communicate intent, such as finding an active subscription or saving an order. Avoid a large generic repository with dozens of methods that expose every possible query shape.

Keep performance visible

A method named findAll() can be dangerous if it loads an unbounded dataset. Include pagination, filtering, and expected result size in the contract. For reporting or specialized read paths, a dedicated query service may be clearer than forcing everything through an aggregate repository.

Manage transactions deliberately

Repositories should not silently open and commit independent transactions when a use case requires several writes to succeed together. Define transaction ownership at the application-service or unit-of-work boundary.

Avoid leaky abstractions

Do not return raw database cursors or provider-specific query builders from a supposedly abstract repository. At the same time, do not hide necessary database-specific optimization when it is important to correctness or scale.

Checklist

  • Model methods around application intent.
  • Make pagination and result limits explicit.
  • Define transaction ownership clearly.
  • Use query services for specialized read models.
  • Keep database-specific behavior documented.
Share this page Help other developers discover this resource.