Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-database

golang-gin-database

Verified

PostgreSQL integration for Go Gin with GORM/sqlx. Use when adding a database, writing queries, creating repositories, running migrations, or wiring DB layers in a Gin project.

references/gorm-patterns-errors.md

View on GitHub
# GORM Patterns — Soft Deletes, Error Handling, and Hooks

Soft delete mechanics, domain error mapping (mapGORMError), and GORM hook trade-offs.

> **Architectural recommendation:** These are mainstream Go/GORM community patterns, not part of the Gin framework API.

## Soft Deletes

Adding `gorm.DeletedAt` to the model activates soft deletes automatically. GORM adds `WHERE deleted_at IS NULL` to all queries.

```go
type UserModel struct {
    // ...
    DeletedAt gorm.DeletedAt `gorm:"index"` // soft delete column
}

// Delete sets deleted_at = NOW() instead of removing the row
r.db.Delete(&UserModel{}, "id = ?", id)

// Query ignores soft-deleted rows by default
r.db.Find(&users) // WHERE deleted_at IS NULL

// Include soft-deleted rows
r.db.Unscoped().Find(&users)

// Hard delete (permanently remove)
r.db.Unscoped().Delete(&UserModel{}, "id = ?", id)
```

**Trade-off:** Soft deletes keep audit history but require `Unscoped()` everywhere you intentionally query deleted records. Consider a dedicated `archived_users` table for large datasets to avoid index bloat.

## Error Handling

Map GORM errors to domain errors. Never leak raw GORM errors to the handler layer.

```go
// internal/repository/errors.go
package repository

import (
    "errors"

    "github.com/jackc/pgx/v5/pgconn"
    "gorm.io/gorm"
    "myapp/internal/domain"
)

// mapGORMError converts a GORM error to a domain error.
func mapGORMError(err error) error {
    if errors.Is(err, gorm.ErrRecordNotFound) {
        return domain.ErrNotFound.New(err)
    }
    // PostgreSQL unique violation (SQLSTATE 23505) — typed assertion, not string matching
    var pgErr *pgconn.PgError
    if errors.As(err, &pgErr) && pgErr.Code == "23505" {
        return domain.ErrConflict.New(err)
    }
    return domain.ErrInternal.New(err)
}
```

**Critical:** Log the raw GORM error at the service layer (it includes the SQL state). Return only the domain error to the handler.

## Hooks — Trade-offs

GORM hooks (`BeforeCreate`, `AfterCreate`, etc.) run automatically but introduce hidden side effects.

```go
// Use hooks for truly cross-cutting concerns (e.g., UUID generation)
func (m *UserModel) BeforeCreate(tx *gorm.DB) error {
    if m.ID == "" {
        m.ID = uuid.Must(uuid.NewV7()).String() // UUIDv7: time-sortable, better B-tree index performance
    }
    return nil
}
```

| Pros | Cons |
|------|------|
| Zero boilerplate for UUID gen | Hidden logic — hard to trace |
| Consistent across all create paths | Can't be disabled per call |
| Works with transactions | Tested separately from service logic |

**Recommendation:** Use hooks for `ID` generation and `UpdatedAt` only. Move business logic (hashing passwords, sending emails) to the service layer where it's explicit and testable.
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall