Fusion
ea6c466c6c
- Add init_database() with alembic programmatic API and retry logic - Add connection retry with exponential backoff (5 attempts) - Improve error messages for connection/auth failures - Add table existence check before seeding data - Update startup event to run migrations before seeding - Add wait-for-db.sh script for Docker containers - Update Docker and docker-compose configurations Quality gates: ruff ✓, mypy ✓, unit tests (8 passed)
2.1 KiB
2.1 KiB
Context
Currently, the application crashes with cryptic SQLAlchemy errors when:
- Database tables don't exist (fresh deployment)
- Migrations haven't been applied
- The database is temporarily unavailable during startup
This requires manual intervention to run alembic upgrade head and restart containers.
Goals / Non-Goals
Goals:
- Automatically run migrations on application startup
- Handle missing tables gracefully with informative error messages
- Add database connection retries for transient failures
- Ensure seed data runs after migrations complete
- Support both development and production Docker deployments
Non-Goals:
- Database backup/recovery (out of scope)
- Complex migration rollback handling
- Multi-master database support
Decisions
-
Run migrations in startup event
- Rationale: Ensures database is always up-to-date before handling requests
- Alternative: Separate init container. Rejected to keep deployment simple.
-
Use alembic programmatic API
- Rationale: Avoids subprocess calls and captures errors properly
- Run via
alembic.command.upgrade()in async context
-
Add connection retry with backoff
- Rationale: Database may not be ready when app starts
- 5 retries with 2-second exponential backoff
-
Graceful error handling
- Rationale: Clear error messages for operators
- Distinguish between: connection refused, auth failed, missing migrations
Risks / Trade-offs
- [Startup delay] -> Migrations run on every startup, but Alembic is idempotent
- [Concurrent startup] -> Multiple instances could race; use advisory locks if needed later
- [Migration failures] -> App won't start; this is correct behavior
Migration Plan
- Add
init_database()function that runs migrations and seed data - Modify startup event to call
init_database()with retries - Update Docker CMD to ensure database is ready
- Test with fresh database volume
Open Questions
- Should we add a separate
db initCLI command for manual runs? - Do we need database connection pooling configuration?