goplt/docs/content/adr/0013-database-orm.md

ADR-0013: Database ORM Selection

Status

Accepted

Context

The platform needs a database ORM/library that:

• Supports PostgreSQL (primary database)
• Provides type-safe query building
• Supports code generation (reduces boilerplate)
• Handles migrations
• Supports relationships (many-to-many, etc.)
• Integrates with Ent (code generation)

Options considered:

1. entgo.io/ent - Code-generated, type-safe ORM
2. gorm.io/gorm - Feature-rich ORM with reflection
3. sqlx - Lightweight wrapper around database/sql
4. Standard library database/sql - No ORM, raw SQL

Decision

Use entgo.io/ent as the primary ORM for the platform.

Rationale:

• Code generation provides compile-time type safety
• Excellent schema definition and migration support
• Strong relationship modeling
• Good performance (no reflection at runtime)
• Active development and good documentation
• Recommended in playbook.md
• Easy to integrate with OpenTelemetry

Consequences

Positive

• Type-safe queries eliminate runtime errors
• Schema changes are explicit and versioned
• Code generation reduces boilerplate
• Good migration support
• Strong relationship support

Negative

• Requires code generation step (go generate)
• Learning curve for developers unfamiliar with Ent
• Less flexible than raw SQL for complex queries
• Generated code must be committed or verified in CI

Implementation Notes

• Install: go get entgo.io/ent/cmd/ent
• Initialize schema: go run entgo.io/ent/cmd/ent init User Role Permission
• Use //go:generate directives for code generation
• Run migrations on startup via client.Schema.Create()
• Create wrapper in internal/infra/database/client.go for DI injection