Repositories and Interfaces in Go
TL;DR — Repository = interface in use-case layer defining what the layer needs. Implementation in adapter layer talks to the actual DB. Methods accept
context.Context, return domain entities. Transactions via a small executor abstraction. No leaky DB types.
After domain entities , the way use cases reach persistent storage. The repository pattern in Go is straightforward once you stop fighting the language.
The interface lives in use-case
Already mentioned in earlier posts. Repeating because it’s the rule that matters:
// internal/usecase/port.go
package usecase
import (
"context"
"github.com/google/uuid"
"yourorg/billing/internal/domain"
)
type SubscriptionRepository interface {
Save(ctx context.Context, s *domain.Subscription) error
GetByID(ctx context.Context, id uuid.UUID) (*domain.Subscription, error)
ListByCustomer(ctx context.Context, customerID uuid.UUID) ([]*domain.Subscription, error)
}
Three things:
- Methods accept
context.Context(cancellation, deadlines) - Inputs are domain types (
*domain.Subscription,uuid.UUID) - Outputs are domain types (no DB row structs leaking)
The interface defines what the use case needs, no more. Don’t pre-emptively add methods. YAGNI.
The Postgres implementation
// internal/adapter/postgres/subscription_repository.go
package postgres
import (
"context"
"errors"
"github.com/google/uuid"
"github.com/jackc/pgx/v4"
"github.com/jackc/pgx/v4/pgxpool"
"yourorg/billing/internal/domain"
)
type SubscriptionRepository struct {
db *pgxpool.Pool
}
func NewSubscriptionRepository(db *pgxpool.Pool) *SubscriptionRepository {
return &SubscriptionRepository{db: db}
}
func (r *SubscriptionRepository) Save(ctx context.Context, s *domain.Subscription) error {
_, err := r.db.Exec(ctx, `
INSERT INTO subscriptions (id, customer_id, plan_id, status, started_at, renews_at, canceled_at)
VALUES ($1, $2, $3, $4, $5, $6, $7)
ON CONFLICT (id) DO UPDATE SET
status = EXCLUDED.status,
renews_at = EXCLUDED.renews_at,
canceled_at = EXCLUDED.canceled_at
`, s.ID(), s.CustomerID(), s.Plan().ID, string(s.Status()), s.StartedAt(), s.RenewsAt(), s.CanceledAt())
return err
}
func (r *SubscriptionRepository) GetByID(ctx context.Context, id uuid.UUID) (*domain.Subscription, error) {
var row subscriptionRow
err := r.db.QueryRow(ctx, `
SELECT id, customer_id, plan_id, status, started_at, renews_at, canceled_at
FROM subscriptions WHERE id = $1
`, id).Scan(&row.ID, &row.CustomerID, &row.PlanID, &row.Status, &row.StartedAt, &row.RenewsAt, &row.CanceledAt)
if errors.Is(err, pgx.ErrNoRows) {
return nil, domain.ErrSubscriptionNotFound
}
if err != nil {
return nil, err
}
return row.toDomain()
}
type subscriptionRow struct {
ID uuid.UUID
CustomerID uuid.UUID
PlanID string
Status string
StartedAt time.Time
RenewsAt time.Time
CanceledAt *time.Time
}
func (r subscriptionRow) toDomain() (*domain.Subscription, error) {
plan, err := loadPlan(r.PlanID) // separate concern
if err != nil {
return nil, err
}
return domain.RestoreSubscription(
r.ID, r.CustomerID, plan,
domain.Status(r.Status),
r.StartedAt, r.RenewsAt, r.CanceledAt,
), nil
}
The subscriptionRow is a private struct that exists only in the adapter to deserialize DB rows. The toDomain() method converts to the domain type. Domain types never know about Postgres.
Note: returns domain.ErrSubscriptionNotFound (defined in domain) when pgx says no rows. Caller checks via errors.Is; doesn’t need to know we’re using pgx.
Transactions
The tricky one. A use case sometimes needs to do “save subscription + publish event” atomically. How without leaking pgx into the use case?
Pattern: Executor interface.
// In usecase/port.go
type Tx interface {
Subscription() SubscriptionRepository
Invoice() InvoiceRepository
Commit(ctx context.Context) error
Rollback(ctx context.Context) error
}
type TxManager interface {
Begin(ctx context.Context) (Tx, error)
}
In Postgres adapter:
type PgTx struct {
tx pgx.Tx
}
func (t *PgTx) Subscription() usecase.SubscriptionRepository {
return &SubscriptionRepository{db: txDB{t.tx}} // adapter that uses tx instead of pool
}
type PgTxManager struct {
pool *pgxpool.Pool
}
func (m *PgTxManager) Begin(ctx context.Context) (usecase.Tx, error) {
tx, err := m.pool.Begin(ctx)
if err != nil { return nil, err }
return &PgTx{tx: tx}, nil
}
Use case:
func (u *Refund) Execute(ctx context.Context, ...) error {
tx, err := u.txMgr.Begin(ctx)
if err != nil { return err }
defer tx.Rollback(ctx) // safe to call after commit
if err := tx.Subscription().Save(ctx, sub); err != nil { return err }
if err := tx.Invoice().Save(ctx, invoice); err != nil { return err }
return tx.Commit(ctx)
}
The use case doesn’t know it’s Postgres. Tx is an interface. The pattern works for any DB.
Alternative: pass Tx into repository methods explicitly. Either works; the interface-per-tx pattern is cleaner.
Avoid the urge to generalize
Tempting to write type Repository[T any] interface { Save(T) error; Get(id) T }. Generic. Reusable. Bad.
Generic repositories accumulate methods nobody needs (FindAll, FindByCriteria, etc.). Each use case wants specific methods. Define specific interfaces per consumer.
Go 1.18 has generics; doesn’t mean every type should use them. Repositories are usually wrong place for them.
Error normalization
Three error categories repositories should distinguish:
- Domain errors:
domain.ErrNotFound, etc. Returned when the situation is meaningful to the use case. - Transient infra errors: connection lost, timeout. Surface as-is for the use case to decide (retry? abort?).
- Constraint violations: unique key, FK. Map to domain errors when meaningful (e.g., duplicate subscription →
domain.ErrDuplicate).
func (r *SubscriptionRepository) Save(ctx context.Context, s *domain.Subscription) error {
_, err := r.db.Exec(ctx, `INSERT ...`, ...)
var pgErr *pgconn.PgError
if errors.As(err, &pgErr) && pgErr.Code == "23505" {
return domain.ErrDuplicateSubscription
}
return err
}
Common Pitfalls
Returning DB row structs from public methods. Adapter detail leaks. Map to domain.
Save() that takes raw fields instead of a domain entity. Defeats encapsulation. Pass *domain.Subscription.
N+1 queries hidden inside repository methods. Repository should expose batch operations: GetByIDs(ctx, ids), ListByCustomer(ctx, id). Caller decides.
No context.Context. Now you can’t cancel, can’t propagate deadlines, can’t trace. Always first arg.
Interface methods with 8+ parameters. Wrap inputs in struct: Save(ctx, input SaveInput). Clearer.
Mock generation as default test approach. Hand-rolled fakes are usually clearer.
Wrapping Up
Repository = port in use-case layer + implementation in adapter layer + tx pattern for atomicity. Domain types only on the public surface. Wednesday: use cases — what calls these repositories.
