goplt/docs/content/stories/epic1/1.2-database-layer.md

Story 1.2: Database Layer with Ent ORM

Metadata

• Story ID: 1.2
• Title: Database Layer with Ent ORM
• Epic: 1 - Core Kernel & Infrastructure
• Status: Completed
• Priority: High
• Estimated Time: 6-8 hours
• Dependencies: 1.1

Goal

Set up database client foundation for services. Each service will have its own database connection pool and schema.

Description

This story implements the database client foundation that services will use. It includes connection management, schema isolation support, connection pooling configuration, and migration runner wrapper. Core domain entities (User, Role, Permission, AuditLog) are NOT implemented here - they are part of their respective services in Epic 2.

Deliverables

1. Database Client Foundation

• Database client wrapper in internal/infra/database/client.go
• Support for schema isolation (each service uses its own schema)
• Connection pooling configuration per service
• Migration runner wrapper
• Database health check integration

2. Database Client Functions

• NewEntClient(dsn string, schema string) (*ent.Client, error) - supports schema isolation
• Connection pooling configuration:
  • Max connections per service
  • Max idle connections per service
  • Connection lifetime
  • Idle timeout
• Per-service connection pool management
• Migration runner wrapper
• Database health check integration
• Graceful connection closing

3. Database Configuration

• Add database config to config/default.yaml:
  • Connection string (DSN) - shared PostgreSQL instance
  • Connection pool settings per service
  • Schema isolation configuration
  • Migration settings
  • Driver configuration

4. Database Client Factory

• Factory function for creating service-specific database clients
• Each service manages its own connection pool
• Support for multiple services connecting to same database instance with different schemas

Implementation Steps

1. Create Database Client Wrapper

   • Create internal/infra/database/client.go
   • Implement NewEntClient(dsn, schema) function
   • Add connection pooling configuration
   • Add schema isolation support

2. Add Configuration

   • Update config/default.yaml
   • Add database configuration section
   • Add schema isolation settings

3. Create Database Client Factory

   • Factory function for service-specific clients
   • Support for per-service connection pools
   • Migration runner wrapper

4. Test Database Client

   • Test connection with schema isolation
   • Test multiple services connecting to same database
   • Test connection pooling

Acceptance Criteria

• Database client connects to PostgreSQL with schema support
• Connection pooling is configured correctly per service
• Database health check works
• Multiple services can connect to same database instance with different schemas
• Each service manages its own connection pool
• Database client factory works correctly
• Schema isolation is supported
• Connections are closed gracefully on shutdown

Note: Core domain entities (User, Role, Permission, AuditLog) are implemented in Epic 2 as part of their respective services (Identity, Authz, Audit).

Related ADRs

• ADR-0013: Database ORM

Implementation Notes

• Use Ent for type-safe database operations
• Configure connection pooling appropriately
• Run migrations on application startup
• Add proper indexes for performance
• Handle database connection errors gracefully
• Support for database migrations in future epics

Testing

# Test Ent schema generation
go generate ./internal/ent
go build ./internal/ent

# Test database connection
go test ./internal/infra/database/...

# Test migrations
go run cmd/platform/main.go

Files to Create/Modify

• internal/infra/database/client.go - Database client wrapper with schema support
• internal/infra/database/factory.go - Database client factory for services
• config/default.yaml - Add database config with schema isolation settings

Note: Entity schemas are created in Epic 2:

• services/identity/ent/schema/user.go - User entity (Identity Service)
• services/authz/ent/schema/role.go - Role entity (Authz Service)
• services/authz/ent/schema/permission.go - Permission entity (Authz Service)
• services/audit/ent/schema/audit_log.go - AuditLog entity (Audit Service)