henriqueatila/golang-gin-best-practices / skills/golang-gin-database
golang-gin-database
VerifiedPostgreSQL 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |