certctl/POSTGRES_IMPLEMENTATION.md

# PostgreSQL Repository Implementation

## Overview
Complete PostgreSQL implementation for the certctl certificate control plane using `database/sql` and `lib/pq` driver. All 71 interface methods across 11 repositories have been implemented.

## File Structure

```
internal/repository/postgres/
├── db.go               # Database connection and migration setup
├── certificate.go      # CertificateRepository (8 methods)
├── issuer.go          # IssuerRepository (5 methods)
├── target.go          # TargetRepository (6 methods)
├── agent.go           # AgentRepository (7 methods)
├── job.go             # JobRepository (9 methods)
├── policy.go          # PolicyRepository (7 methods)
├── audit.go           # AuditRepository (2 methods)
├── notification.go    # NotificationRepository (3 methods)
├── team.go            # TeamRepository (5 methods)
└── owner.go           # OwnerRepository (5 methods)
```

## Key Implementation Details

### Database Connection (db.go)
- `NewDB(connStr string)` - Opens PostgreSQL connection with connection pooling
  - Max open connections: 25
  - Max idle connections: 5
  - Verifies connection with Ping()

- `RunMigrations(db, migrationsPath)` - Executes SQL migration files
  - Reads all `.sql` files from migrations directory
  - Executes files in alphabetical order
  - Simple approach without external migration library

### Data Patterns Used

1. **UUID Generation**: Using `github.com/google/uuid` for ID generation
2. **Parameterized Queries**: All queries use `$1, $2, etc.` parameter placeholders
3. **Context Propagation**: All database operations use `*Context` variants
4. **Nullable Types**:
   - `sql.NullTime` for optional timestamps
   - `sql.NullString` for optional strings
5. **JSON Handling**:
   - `json.Marshal/Unmarshal` for JSONB columns
   - Config fields stored as `json.RawMessage`
6. **Array Handling**:
   - `pq.Array()` for storing Go slices in PostgreSQL arrays
   - `pq.StringArray` for scanning string arrays
7. **RETURNING Clauses**: Used in CREATE operations to retrieve generated IDs

### Error Handling
- All errors wrapped with `fmt.Errorf` for context
- Specific error messages for not found cases
- Row count verification for UPDATE/DELETE operations

## Repository Implementations

### CertificateRepository (8 methods)
- Manages certificate lifecycle with filtering by status, environment, owner, team, issuer
- Pagination support (default 50, max 500 per page)
- Certificate versioning with history tracking
- Expiration tracking and notifications
- Tags stored as JSON

### IssuerRepository (5 methods)
- Manages certificate authorities (ACME, GenericCA)
- Configuration stored as JSON for flexibility
- Enable/disable issuers

### TargetRepository (6 methods)
- Manages deployment targets (NGINX, F5, IIS)
- Lists targets associated with certificates via join table
- Configuration stored as JSON

### AgentRepository (7 methods)
- Manages control plane agents with status tracking
- Heartbeat update functionality
- API key hash lookup for authentication
- Last heartbeat timestamp tracking

### JobRepository (9 methods)
- Manages renewal, deployment, issuance, and validation jobs
- Status tracking with error messages
- Attempt counters for retry logic
- Pending job retrieval by type
- Filtering by status and certificate

### PolicyRepository (7 methods)
- Policy rules with multiple enforcement types
- Policy violation recording and querying
- Configurable rules stored as JSON
- Severity levels for violations (Warning, Error, Critical)

### AuditRepository (2 methods)
- Records all control plane actions
- Filtering by actor, resource type, time range
- Pagination support
- Details stored as JSON

### NotificationRepository (3 methods)
- Notification event tracking
- Multiple channels (Email, Webhook, Slack)
- Delivery status tracking
- Certificate-specific notification filtering

### TeamRepository (5 methods)
- Organizational unit management
- Basic CRUD operations
- Team descriptions for organization

### OwnerRepository (5 methods)
- Certificate owner management
- Email field for notifications
- Team affiliation tracking
- Basic CRUD operations

## Database Assumptions

The implementation expects the following table structures:

**certificates**
- id, name, common_name, sans (array), environment, owner_id, team_id, issuer_id
- status, expires_at, tags (json), last_renewal_at, last_deployment_at
- created_at, updated_at

**certificate_versions**
- id, certificate_id, serial_number, not_before, not_after
- fingerprint_sha256, pem_chain, csr_pem, created_at

**certificate_target_mappings** (join table)
- certificate_id, target_id

**issuers**
- id, name, type, config (json), enabled, created_at, updated_at

**deployment_targets**
- id, name, type, agent_id, config (json), enabled, created_at, updated_at

**agents**
- id, name, hostname, status, last_heartbeat_at, registered_at, api_key_hash

**jobs**
- id, type, certificate_id, target_id, status, attempts, max_attempts
- last_error, scheduled_at, started_at, completed_at, created_at

**policy_rules**
- id, name, type, config (json), enabled, created_at, updated_at

**policy_violations**
- id, certificate_id, rule_id, message, severity, created_at

**audit_events**
- id, actor, actor_type, action, resource_type, resource_id, details (json), timestamp

**notifications**
- id, type, certificate_id, channel, recipient, message, sent_at, status, error, created_at

**teams**
- id, name, description, created_at, updated_at

**owners**
- id, name, email, team_id, created_at, updated_at

## Integration Points

Constructor functions for each repository:
```go
NewCertificateRepository(db *sql.DB) *CertificateRepository
NewIssuerRepository(db *sql.DB) *IssuerRepository
NewTargetRepository(db *sql.DB) *TargetRepository
NewAgentRepository(db *sql.DB) *AgentRepository
NewJobRepository(db *sql.DB) *JobRepository
NewPolicyRepository(db *sql.DB) *PolicyRepository
NewAuditRepository(db *sql.DB) *AuditRepository
NewNotificationRepository(db *sql.DB) *NotificationRepository
NewTeamRepository(db *sql.DB) *TeamRepository
NewOwnerRepository(db *sql.DB) *OwnerRepository
```

## Dependencies
- `database/sql` (stdlib)
- `github.com/lib/pq` v1.10.9
- `github.com/google/uuid` v1.6.0

## Notes

1. All list operations support pagination with configurable page size (default 50, max 500)
2. Filtering is dynamic - only conditions with non-empty values are added to WHERE clause
3. Timestamps use `time.Time` for CreatedAt/UpdatedAt with automatic Now() on updates
4. Array fields use `pq.Array()` for proper PostgreSQL array handling
5. Nullable fields use `sql.Null*` types for proper NULL handling
6. All operations are context-aware and respect cancellation signals
7. Error messages are descriptive and wrapped for debugging