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

ADR-0013: Database ORM Selection

Status

Accepted

Context

The platform follows a microservices architecture where each service has its own database connection. The ORM/library must:

• Support PostgreSQL (primary database)
• Provide type-safe query building
• Support code generation (reduces boilerplate)
• Handle migrations per service
• Support relationships (many-to-many, etc.)
• Integrate with Ent (code generation)
• Support schema isolation (each service owns its schema)

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

Database Access Pattern

• Each service has its own database connection pool: Services do not share database connections
• Schema isolation: Each service owns its database schema (e.g., auth_schema, identity_schema, blog_schema)
• No cross-service database access: Services communicate via APIs, not direct database queries
• Shared database instance: Services share the same PostgreSQL instance but use different schemas
• Alternative: Database-per-service pattern (each service has its own database) for maximum isolation

Implementation Notes

• Install: go get entgo.io/ent/cmd/ent
• Each service initializes its own schema: go run entgo.io/ent/cmd/ent init User Role Permission (Identity Service)
• Use //go:generate directives for code generation per service
• Run migrations on startup via client.Schema.Create() for each service
• Create database client wrapper per service in services/{service}/internal/database/client.go
• Each service manages its own connection pool configuration