65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
# 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
|
|
|