repository

Generic Repository with Go Generics and Bun ORM

A generic implementation of a data access layer using Go generics and Bun ORM.

Features

• Generic repository pattern implementation
• CRUD operations with transactional support
• Dynamic query building with criteria functions
• Custom identifiers and UUID support
• Soft delete capabilities
• Raw query execution
• Bulk operations (CreateMany, UpdateMany, UpsertMany)
• GetOrCreate and Upsert convenience methods
• Map-native struct/map projection and patch helpers (no JSON roundtrip)
• Multi-database support (PostgreSQL, SQLite, MSSQL, MySQL)
• Sophisticated error handling with categorized errors
• Model metadata extraction and field introspection
• Transaction management utilities
• Comprehensive test coverage

Installation

go get github.com/goliatone/go-repository-bun

Development Quality

This repository uses a taskfile-based Go quality workflow:

./taskfile go:tools:all
./taskfile go:fmt:check
./taskfile go:test
./taskfile go:lint:baseline
./taskfile go:quality:baseline

golangci-lint, govulncheck, and gosec are managed through ./taskfile. Existing lint and security findings are tracked in ops/quality/baselines/ so new work can be checked without requiring a full backlog cleanup first.

Usage

Import the package

import (
    repository "github.com/goliatone/go-repository-bun"
    "github.com/uptrace/bun"
    "github.com/google/uuid"
)

Defining Models

type User struct {
    bun.BaseModel `bun:"table:users,alias:u"`

    ID        uuid.UUID  `bun:"id,pk,notnull"`
    Name      string     `bun:"name,notnull"`
    Email     string     `bun:"email,notnull,unique"`
    DeletedAt *time.Time `bun:"deleted_at,soft_delete"`
    CreatedAt time.Time  `bun:"created_at,notnull"`
    UpdatedAt time.Time  `bun:"updated_at,notnull"`
}

Creating Repository

// Define handlers for your model
handlers := repository.ModelHandlers[*User]{
    NewRecord: func() *User {
        return &User{}
    },
    GetID: func(record *User) uuid.UUID {
        if record == nil {
            return uuid.Nil
        }
        return record.ID
    },
    SetID: func(record *User, id uuid.UUID) {
        record.ID = id
    },
    GetIdentifier: func() string {
        return "email" // Unique identifier field
    },
    GetIdentifierValue: func(record *User) string {
        if record == nil {
            return ""
        }
        return record.Email
    },
    ResolveIdentifier: func(identifier string) []repository.IdentifierOption {
        identifier = strings.TrimSpace(identifier)
        if identifier == "" {
            return nil
        }

        var lookups []repository.IdentifierOption

        if strings.Contains(identifier, "@") {
            lookups = append(lookups, repository.IdentifierOption{
                Column: "email",
                Value:  strings.ToLower(identifier),
            })
        }

        if _, err := uuid.Parse(identifier); err == nil {
            lookups = append(lookups, repository.IdentifierOption{
                Column: "id",
            })
        }

        // Always try username as a fallback.
        lookups = append(lookups, repository.IdentifierOption{
            Column: "username",
        })

        return lookups
    },
}

// Create repository instance
userRepo := repository.MustNewRepository[*User](db, handlers)

ResolveIdentifier is optional. When provided, the repository will try each returned IdentifierOption (column/value pair) in order until a record is found. Returning nil or an empty slice falls back to the default GetIdentifier/GetIdentifierValue behaviour.

For Upsert* and GetOrCreate*, you can also configure a composite/natural key resolver through repo options:

userRepo := repository.MustNewRepositoryWithConfig[*User](
    db,
    handlers,
    nil, // db options
    repository.WithRecordLookupResolver(func(record *User) []repository.SelectCriteria {
        if record == nil {
            return nil
        }
        return []repository.SelectCriteria{
            repository.SelectBy("company_id", "=", record.CompanyID.String()),
            repository.SelectBy("name", "=", record.Name),
            // Optional domain ordering
            repository.OrderBy("updated_at DESC"),
        }
    }),
)

Lookup precedence in Upsert*/GetOrCreate* is:

1. ID
2. identifier (GetIdentifierValue)
3. WithRecordLookupResolver criteria

If resolver criteria are used, the repository appends a stable id ASC tie breaker to guarantee deterministic selection when criteria are not unique.

WithRecordLookupResolver is type checked against the repository model type. Mismatches fail validation and will fail Upsert*/GetOrCreate* fast if not validated explicitly.

Basic Operations

// Create
user := &User{Name: "John Doe", Email: "john.doe@example.com"}
created, err := userRepo.Create(ctx, user)

// Retrieve by ID
user, err := userRepo.GetByID(ctx, "user-uuid")

// Retrieve by identifier (email in this case)
user, err := userRepo.GetByIdentifier(ctx, "john.doe@example.com")

// Update
user.Name = "Jane Doe"
updated, err := userRepo.Update(ctx, user)

// Delete (soft delete if DeletedAt field exists)
err := userRepo.Delete(ctx, user)

// Force delete (permanent delete)
err := userRepo.ForceDelete(ctx, user)

Bulk Operations

// Create multiple records
users := []*User{
    {Name: "User 1", Email: "user1@example.com"},
    {Name: "User 2", Email: "user2@example.com"},
}
created, err := userRepo.CreateMany(ctx, users)

// Update multiple records
updated, err := userRepo.UpdateMany(ctx, users)

// Optional: reorder returned records to match input IDs
created, err = userRepo.CreateMany(ctx, users, repository.InsertReturnOrderByID())
updated, err = userRepo.UpdateMany(ctx, users, repository.UpdateReturnOrderByID())

// Upsert multiple records
upserted, err := userRepo.UpsertMany(ctx, users)

Convenience Methods

// Get or create
user := &User{Email: "new@example.com", Name: "New User"}
result, err := userRepo.GetOrCreate(ctx, user)

// Upsert (update if exists, create if not)
user := &User{ID: someID, Name: "Updated Name", Email: "email@example.com"}
result, err := userRepo.Upsert(ctx, user)

Scopes

Scopes let you register reusable filters that are applied automatically to repository operations.

const tenantScope = "tenant"

userRepo.RegisterScope(tenantScope, repository.ScopeDefinition{
    Select: func(ctx context.Context) []repository.SelectCriteria {
        value, ok := repository.ScopeData(ctx, tenantScope)
        if !ok {
            return nil
        }
        tenantID, ok := value.(uuid.UUID)
        if !ok || tenantID == uuid.Nil {
            return nil
        }
        return []repository.SelectCriteria{
            repository.SelectBy("company_id", "=", tenantID.String()),
        }
    },
})

if err := userRepo.SetScopeDefaults(repository.ScopeDefaults{
    Select: []string{tenantScope},
}); err != nil {
    panic(err)
}

To avoid duplicating the same guard logic in every scope, register the helper instead:

userRepo.RegisterScope(tenantScope, repository.ScopeByField(tenantScope, "company_id"))

ScopeByField is fail-closed: when scope data is missing/invalid, it adds a no-match predicate.

For explicit fail-open behavior (legacy), use ScopeByFieldOptional:

userRepo.RegisterScope(tenantScope, repository.ScopeByFieldOptional(tenantScope, "company_id"))

Activate scopes through the context. Default scopes run automatically unless disabled:

ctx := repository.WithScopeData(ctx, tenantScope, tenantID)
users, total, err := userRepo.List(ctx) // tenant scope applied

ctx = repository.WithoutDefaultScopes(ctx)
ctx = repository.WithSelectScopes(ctx, tenantScope)
ctx = repository.WithScopeData(ctx, tenantScope, tenantID)
users, total, err = userRepo.List(ctx) // scope applied explicitly

Other operations can be scoped with WithInsertScopes, WithUpdateScopes, and WithDeleteScopes.

When scope data is missing or empty, ScopeByField/ScopeByFieldRequired add a no-match predicate so queries fail closed. If you need fail-open behavior, use ScopeByFieldOptional. To surface configuration mistakes early, SetScopeDefaults validates that every default references a registered scope and returns a validation error otherwise.

If you need to propagate the active scope set into other infrastructure (for example, cache decorators), use repository.ResolveScopeState(ctx, defaults, repository.ScopeOperationSelect) together with repository.ScopeDataSnapshot(ctx) to build deterministic signatures.

For repositories that need explicit tenant/org predicates instead of registered context scopes, use the lower-level scope helpers:

expr, args, ok := repository.ScopeWhere(
	repository.ScopeColumns{Tenant: "cf.tenant_id", Org: "cf.org_id"},
	repository.ScopeValues{TenantID: tenantID, OrgID: orgID},
	repository.ScopeExact,
)
if ok {
	query = query.Where(expr, args...)
}

Supported modes are:

• ScopeExact: match the provided tenant/org exactly and fail closed when a configured column has no value.
• ScopeGlobal: match blank/global rows only.
• ScopeExactOrGlobal: match exact rows or blank/global rows where explicitly allowed by the caller.

SelectScope, UpdateScope, and DeleteScope apply the generated predicates directly to Bun queries. DefaultScope(record, values) and DefaultScopeMap(values, scope) fill missing tenant/org values on scoped records or metadata maps before persistence. These helpers are app-agnostic: the caller decides whether single-tenant defaults, multi-tenant actor claims, or global fallback are allowed.

Query Criteria

// Legacy constructors keep compatibility defaults: LIMIT 25 OFFSET 0.
userRepo := repository.MustNewRepository[*User](db, handlers)
users, total, err := userRepo.List(ctx)

// List with pagination
users, total, err := userRepo.List(ctx,
    repository.SelectPaginate(10, 0),
    repository.OrderBy("created_at DESC"),
)

// Unsafe identifier/operator inputs are ignored or fail closed.
// Column names and operators are validated internally.
users, total, err = userRepo.List(ctx,
    repository.SelectBy("status", "=", "active"),
)

// Complex queries
users, total, err := userRepo.List(ctx,
    repository.SelectBy("status", "=", "active"),
    repository.SelectColumns("id", "name", "email"),
    repository.SelectRelation("Profile"),
    repository.SelectRawProcessor(func(q *bun.SelectQuery) *bun.SelectQuery {
        return q.Where("created_at > ?", time.Now().Add(-24*time.Hour)).
                WhereOr("updated_at > ?", time.Now().Add(-1*time.Hour))
    }),
)

// Count records
count, err := userRepo.Count(ctx,
    repository.SelectBy("status", "=", "active"),
)

// Delete with criteria
err := userRepo.DeleteWhere(ctx,
    repository.DeleteBy("status", "=", "inactive"),
    repository.DeleteByTimetz("created_at", "<", time.Now().Add(-365*24*time.Hour)),
)

// Delete by ID list
err = userRepo.DeleteWhere(ctx, repository.DeleteByIDs([]string{"id-1", "id-2"}))

DeleteWhere/DeleteMany now require at least one non-nil criteria function by default. To explicitly allow full-table deletes, configure:

userRepo := repository.MustNewRepositoryWithConfig[*User](
    db,
    handlers,
    nil,
    repository.WithAllowFullTableDelete(true),
)

Use the config constructor to disable implicit pagination defaults:

userRepo := repository.MustNewRepositoryWithConfig[*User](
    db,
    handlers,
    nil, // db options
    // no repo options => no implicit LIMIT/OFFSET
)

You can also set per repository defaults explicitly:

userRepo := repository.MustNewRepositoryWithConfig[*User](
    db,
    handlers,
    nil, // db options
    repository.WithDefaultListPagination(50, 0),
)

Runtime mutation is also available via SetDefaultListPagination(limit, offset), but it should be treated as an initialization stage setting. Changing defaults in live concurrent systems can lead to mixed pagination behavior across requests.

SetDefaultListPagination is exposed via the optional DefaultListPaginationConfigurer interface (not the base Repository interface):

if cfg, ok := userRepo.(repository.DefaultListPaginationConfigurer); ok {
    cfg.SetDefaultListPagination(25, 0)
}

Migration note: NewRepository and NewRepositoryWithOptions preserve legacy LIMIT 25 OFFSET 0 behavior for compatibility. To opt into unbounded default list behavior, use NewRepositoryWithConfig(..., nil) (or pass repo options explicitly).

Transactions

// Using manual transactions
tx, err := db.BeginTx(ctx, nil)
if err != nil {
    return err
}
defer tx.Rollback()

user, err := userRepo.CreateTx(ctx, tx, user)
if err != nil {
    return err
}

// All repository methods have Tx variants
updated, err := userRepo.UpdateTx(ctx, tx, user)
if err != nil {
    return err
}

err = tx.Commit()

Raw Queries

// Execute raw SQL queries
users, err := userRepo.Raw(ctx,
    "SELECT * FROM users WHERE created_at > ? AND status = ?",
    time.Now().Add(-24*time.Hour),
    "active",
)

Error Handling

The package provides categorized errors for better error handling:

err := userRepo.Create(ctx, user)
if err != nil {
    if repository.IsRecordNotFound(err) {
        // Handle not found
    }
    if repository.IsDuplicatedKey(err) {
        // Handle duplicate
    }
    if repository.IsConstraintViolation(err) {
        // Handle constraint violation
    }
    // Other error categories available
}

Map Native Helpers

Use map-native helpers when integrating generic admin adapters that exchange map[string]any.

mapper := repository.NewMapRecordMapper[*User](repository.MapRecordMapperConfig{
    ProjectionOptions: []repository.MapProjectionOption{
        repository.WithProjectionKeyMode(repository.MapKeyBun), // default
    },
    PatchOptions: []repository.MapPatchOption{
        repository.WithPatchKeyMode(repository.MapKeyBun), // default
        repository.WithPatchAllowedFields("name", "email", "updated_at"),
    },
})

payload := map[string]any{
    "name": "Updated Name",
}

record, err := mapper.ToRecord(payload)
asMap, err := mapper.ToMap(record)
patched, columns, err := mapper.ApplyPatch(record, payload)
_ = columns // Bun column names changed by the patch

ID based safe partial update flow:

updated, err := repository.UpdateByIDWithMapPatch(
    ctx,
    userRepo,
    userID,
    map[string]any{"name": "Updated Name"},
    nil, // optional update criteria
    repository.WithPatchAllowedFields("name"),
)

Direct query update criteria from a map payload:

criteria, err := repository.UpdateCriteriaForMapPatch(
    map[string]any{"name": "Updated Name"},
    repository.WithPatchAllowedFields("name"),
)
if err != nil {
    return err
}
// criteria includes UpdateColumns("name") + UpdateSetColumn("name", ...)

"Not found" checks support both helper and sentinel:

if repository.IsRecordNotFound(err) || errors.Is(err, repository.ErrRecordNotFound) {
    // handle not found
}

Advanced Features

Model Metadata

The package provides utilities to extract model metadata and field information:

// Get model fields with database metadata
fields := repository.GetModelFields(db, &User{})
for _, field := range fields {
    fmt.Printf("Field: %s, PK: %v, Type: %s\n", field.Name, field.IsPK, field.SQLType)
}

// Generate complete model metadata including JSON tags and validations
meta := repository.GenerateModelMeta(&User{})
fmt.Printf("Table: %s\n", meta.TableName)
for _, field := range meta.Fields {
    fmt.Printf("Field: %s, Required: %v, Unique: %v\n",
        field.Name, field.IsRequired, field.IsUnique)
}

Transaction Management

The package includes a TransactionManager interface for managing database transactions:

type TransactionManager interface {
    RunInTx(ctx context.Context, opts *sql.TxOptions,
        f func(ctx context.Context, tx bun.Tx) error) error
}

Database Support

The repository automatically detects and adapts to different database drivers:

• PostgreSQL
• SQLite
• MSSQL
• MySQL

Database driver detection is handled automatically via the DetectDriver function.

Project Structure

• repo.go - Main repository implementation and DetectDriver function
• errors.go - Custom error types and handlers
• meta.go - Model metadata extraction utilities
• types.go - Type definitions and interfaces
• utils.go - Utility functions including error helpers
• query_*_criteria.go - Query builder criteria functions
• examples/ - Example usage and model definitions

License

MIT