Repository adapters
Use this skill when
- Adding a repository method, changing a query, or touching an adapter between domain and DB.
- Mapping DB-specific errors to domain errors at the adapter boundary.
- Adding support for a new DB dialect to an existing repository interface.
Do not use this skill when
- The work is the migration itself (use
database-migrations).
- The main risk is Cloudflare D1 runtime query performance without schema changes; use
cloudflare-d1-query-tuning.
- The change is above the adapter layer (services, handlers, or HTTP contracts).
Inputs to gather
- The domain interface definition and every adapter that implements it.
- The generator in use (sqlc, gorm gen, etc.) and its regeneration command.
- Which DB dialects are mandatory vs optional in this repository.
First move
- Update the query source for each dialect, regenerate, then adjust the adapter to call the new or changed query before touching tests.
Outputs
- Updated repository-layer inputs such as query sources, regenerated artifacts, and adapter implementation changes at the domain boundary.
- DB-to-domain error mapping preserved or corrected for the touched operations so adapter callers keep the expected contract.
- Test evidence for the primary adapter path, with optional dialects skipping cleanly when unavailable.
Architecture pattern
Domain interface (repository.go) ← handlers depend on this
↓
Adapter implementation (sqlite.go, postgres.go, etc.)
↓
Generated query layer (if using sqlc, gorm gen, etc.) ← never edit by hand
- Domain interface: defines what persistence operations exist; lives with the domain, not with the DB.
- Adapter: implements the domain interface using DB-specific queries.
- Generated layer: produced by a code generator; editing it by hand is overwritten on next generation.
Safe change workflow
- Update the query source (SQL file, ORM definition) for each DB dialect.
- Regenerate:
make generate
- Update the adapter implementation to call the new or changed query.
- Add or update tests covering the changed behaviour.
- Run:
make test
Error mapping rules
Map DB-level errors to domain errors at the adapter boundary — never let DB-specific errors leak to callers:
| DB error |
Domain error |
| Uniqueness/constraint violation |
ErrDuplicate or equivalent |
| No rows / not found |
ErrNotFound or equivalent |
| Unknown DB error |
Wrap with context: fmt.Errorf("operation context: %w", err) |
Never include raw DB error strings in responses or logs — they expose implementation details and may contain sensitive data.
Workflow
- Identify the domain interface and which DB dialect adapters implement it.
- Update query sources for each dialect that must stay in sync.
- Regenerate query code through the repo's normal generation path — never hand-edit generated files.
- Adjust adapters to call new/changed queries while preserving the shared domain interface.
- Keep DB-to-domain error mapping intact (
%w / equivalent) so callers can use typed error checks.
- Add or update adapter tests; skip optional dialects cleanly when unavailable.
- Run generation checks, unit/adapter tests, and confirm no raw DB errors leak outward.
Guardrails
- Never edit generated query files by hand.
- Each DB dialect's adapter must implement the same domain interface — no adapter-specific methods exposed to callers.
- Error wrapping must use
%w to preserve the error chain for errors.Is / errors.As.
- Optional DB support (e.g. Postgres when only SQLite is required) must skip gracefully in tests, not fail.
- Never leak raw DB error strings in API responses or logs.
Validation
make test # SQLite (or primary DB) must pass; optional DBs skip when unavailable
Reference files
- Read
references/examples.md when you need concrete user utterances, expected behaviour, or a model answer shape to mirror.
- Read
references/edge-cases.md when the request is a near miss, partially matches this skill, or the first attempt fails.
1---2name: repository-adapters3description: "Implement or modify database repository adapters. Use when adding adapter methods, changing queries, or mapping database errors while preserving domain boundaries."4license: GNU GPL v35metadata:6 source: https://skillmd.com/skills/matt-riley/repository-adapters7 version: 1.3.2 # x-release-please-version8 owner: mattriley9 category: data10 audience: general-coding-agent11 maturity: stable12 kind: task13---1415# Repository adapters1617## Use this skill when1819- Adding a repository method, changing a query, or touching an adapter between domain and DB.20- Mapping DB-specific errors to domain errors at the adapter boundary.21- Adding support for a new DB dialect to an existing repository interface.2223## Do not use this skill when2425- The work is the migration itself (use `database-migrations`).26- The main risk is Cloudflare D1 runtime query performance without schema changes; use `cloudflare-d1-query-tuning`.27- The change is above the adapter layer (services, handlers, or HTTP contracts).2829## Inputs to gather3031- The domain interface definition and every adapter that implements it.32- The generator in use (sqlc, gorm gen, etc.) and its regeneration command.33- Which DB dialects are mandatory vs optional in this repository.3435## First move3637- Update the query source for each dialect, regenerate, then adjust the adapter to call the new or changed query before touching tests.3839## Outputs4041- Updated repository-layer inputs such as query sources, regenerated artifacts, and adapter implementation changes at the domain boundary.42- DB-to-domain error mapping preserved or corrected for the touched operations so adapter callers keep the expected contract.43- Test evidence for the primary adapter path, with optional dialects skipping cleanly when unavailable.4445## Architecture pattern4647```48Domain interface (repository.go) ← handlers depend on this49 ↓50Adapter implementation (sqlite.go, postgres.go, etc.)51 ↓52Generated query layer (if using sqlc, gorm gen, etc.) ← never edit by hand53```5455- **Domain interface**: defines what persistence operations exist; lives with the domain, not with the DB.56- **Adapter**: implements the domain interface using DB-specific queries.57- **Generated layer**: produced by a code generator; editing it by hand is overwritten on next generation.5859## Safe change workflow60611. Update the query source (SQL file, ORM definition) for each DB dialect.622. Regenerate: `make generate`633. Update the adapter implementation to call the new or changed query.644. Add or update tests covering the changed behaviour.655. Run: `make test`6667## Error mapping rules6869Map DB-level errors to domain errors **at the adapter boundary** — never let DB-specific errors leak to callers:7071| DB error | Domain error |72| ------------------------------- | ------------------------------------------------------------- |73| Uniqueness/constraint violation | `ErrDuplicate` or equivalent |74| No rows / not found | `ErrNotFound` or equivalent |75| Unknown DB error | Wrap with context: `fmt.Errorf("operation context: %w", err)` |7677**Never** include raw DB error strings in responses or logs — they expose implementation details and may contain sensitive data.7879## Workflow80811. Identify the domain interface and which DB dialect adapters implement it.822. Update query sources for each dialect that must stay in sync.833. Regenerate query code through the repo's normal generation path — never hand-edit generated files.844. Adjust adapters to call new/changed queries while preserving the shared domain interface.855. Keep DB-to-domain error mapping intact (`%w` / equivalent) so callers can use typed error checks.866. Add or update adapter tests; skip optional dialects cleanly when unavailable.877. Run generation checks, unit/adapter tests, and confirm no raw DB errors leak outward.8889## Guardrails9091- Never edit generated query files by hand.92- Each DB dialect's adapter must implement the same domain interface — no adapter-specific methods exposed to callers.93- Error wrapping must use `%w` to preserve the error chain for `errors.Is` / `errors.As`.94- Optional DB support (e.g. Postgres when only SQLite is required) must **skip** gracefully in tests, not fail.95- Never leak raw DB error strings in API responses or logs.9697## Validation9899```bash100make test # SQLite (or primary DB) must pass; optional DBs skip when unavailable101```102103## Reference files104105- Read `references/examples.md` when you need concrete user utterances, expected behaviour, or a model answer shape to mirror.106- Read `references/edge-cases.md` when the request is a near miss, partially matches this skill, or the first attempt fails.