Repositories

Execution Workflow

1. Choose the base repository class that matches the runtime: SQLAlchemyAsyncRepository, SQLAlchemySyncRepository, or a slug or query variant.
2. Set model_type immediately and keep repositories model-specific.
3. Use built-in filters and list_and_count() for list endpoints instead of reimplementing pagination logic.
4. Use bulk helpers for inserts, updates, upserts, and deletes when the workload is batch-shaped.
5. Keep transaction ownership outside the repository unless the framework integration explicitly handles commit behavior.

Implementation Rules

• Keep repositories focused on persistence and query composition, not HTTP contracts.
• Prefer repository subclasses over duplicated ad hoc helper functions spread across handlers.
• Reach for query repositories only when custom SQL or aggregation work is materially different from standard CRUD.
• Keep loader options explicit so relationship behavior is predictable.

Example Pattern