congiuluc/repository-dapper

Repository Pattern — Dapper

When to Use

• Performance-critical read queries (reporting, dashboards, analytics)
• Scenarios requiring raw SQL or stored procedures
• Lightweight read models that don't need change tracking
• Multi-mapping queries joining multiple tables into complex DTOs
• Bulk insert/update operations
• When you need full control over the generated SQL

When to Use EF Core Instead

• LINQ-based queries with compile-time type safety
• Change tracking and unit-of-work patterns
• Schema migrations with dotnet ef
• Complex navigation properties and lazy/eager loading
• Use the repository-efcore skill for those cases

Official Documentation

• Dapper GitHub
• Dapper — Getting Started
• Repository Pattern
• SqlClient Documentation
• Npgsql Documentation

Procedure

1. Define entity in Core with string Id property — see domain models
2. If new interface methods needed, extend IRepository<T> in Core
3. Create Dapper implementation: Dapper implementation
4. For advanced queries: advanced patterns
5. Register via DI configuration
6. Review sample repository for complete pattern
7. Write tests for the implementation
8. Manage schema with SQL migration scripts or a migration tool

Key Principles

• Always use parameterized queries — never concatenate user input into SQL
• Use using statements for IDbConnection — connections are lightweight and pooled
• Use CommandType.StoredProcedure when calling stored procedures
• Prefer QueryAsync<T> over Query<T> for async operations
• Use ConfigureAwait(false) in all async repository methods
• Always accept CancellationToken in repository methods (via CommandDefinition)
• Use IReadOnlyList<T> for collection returns — prevent mutation by callers
• Use IDbConnectionFactory for testability — never new SqlConnection() directly