headquarter/openspec/changes/archive/2026-05-18-database-setup-recovery/tasks.md

1. Database Initialization

• 1.1 Create init_database() function in apps/api/src/database.py
• 1.2 Add alembic programmatic upgrade call
• 1.3 Add connection retry logic with backoff
• 1.4 Modify startup event to call init_database() before seeding
• 1.5 Update seed functions to check table existence first

2. Error Handling and Logging

• 2.1 Add clear error messages for connection failures
• 2.2 Add clear error messages for missing tables
• 2.3 Add clear error messages for auth failures
• 2.4 Log migration status on startup

3. Docker Integration

• 3.1 Update Dockerfile to wait for database readiness
• 3.2 Update docker-compose files with init order
• 3.3 Add health check script for database

4. Testing

• 4.1 Test with fresh database (no tables)
• 4.2 Test with existing database (migrations already applied)
• 4.3 Test database connection failure handling
• 4.4 Run quality gates (ruff, mypy, pytest)