# 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