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 a complete database layer using Ent ORM with core domain entities, migrations, and connection management.

Description

This story implements the complete database layer using Ent ORM. It includes defining core domain entities (User, Role, Permission, AuditLog), setting up migrations, configuring connection pooling, and creating a database client that integrates with the DI container.

Deliverables

1. Ent Schema Initialization

• Initialize Ent schema in internal/ent/
• Set up code generation

2. Core Domain Entities (internal/ent/schema/)

Define core entities:

• User (user.go): ID, email, password_hash, verified, created_at, updated_at
• Role (role.go): ID, name, description, created_at
• Permission (permission.go): ID, name (format: "module.resource.action")
• AuditLog (audit_log.go): ID, actor_id, action, target_id, metadata (JSON), timestamp
• Relationships:
  • role_permissions.go - Many-to-many between Role and Permission
  • user_roles.go - Many-to-many between User and Role

3. Generated Ent Code

• Run go generate ./internal/ent
• Verify generated code compiles
• Type-safe database operations

4. Database Client (internal/infra/database/client.go)

• NewEntClient(dsn string) (*ent.Client, error) function
• Connection pooling configuration:
  • Max connections
  • Max idle connections
  • Connection lifetime
  • Idle timeout
• Migration runner wrapper
• Database health check integration
• Graceful connection closing

5. Database Configuration

• Add database config to config/default.yaml:
  • Connection string (DSN)
  • Connection pool settings
  • Migration settings
  • Driver configuration

6. DI Integration

• Provider function for database client
• Register in DI container
• Lifecycle management (close on shutdown)

Implementation Steps

1. Install Ent

   go get entgo.io/ent/cmd/ent
   

2. Initialize Ent Schema

   go run entgo.io/ent/cmd/ent init User Role Permission AuditLog
   

3. Define Core Entities

   • Create schema files for each entity
   • Define fields and relationships
   • Add indexes where needed

4. Generate Ent Code

   go generate ./internal/ent
   

5. Create Database Client

   • Create internal/infra/database/client.go
   • Implement connection management
   • Add migration runner
   • Add health check

6. Add Configuration

   • Update config/default.yaml
   • Add database configuration section

7. Integrate with DI

   • Create provider function
   • Register in container
   • Test connection

Acceptance Criteria

• Ent schema compiles and generates code successfully
• Database client connects to PostgreSQL
• Core entities can be created and queried
• Migrations run successfully on startup
• Connection pooling is configured correctly
• Database health check works
• All entities have proper indexes and relationships
• Database client is injectable via DI
• Connections are closed gracefully on shutdown

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/ent/schema/user.go - User entity
• internal/ent/schema/role.go - Role entity
• internal/ent/schema/permission.go - Permission entity
• internal/ent/schema/audit_log.go - AuditLog entity
• internal/ent/schema/role_permissions.go - Relationship
• internal/ent/schema/user_roles.go - Relationship
• internal/infra/database/client.go - Database client
• internal/di/providers.go - Add database provider
• config/default.yaml - Add database config