Fusion
59 lines
2.1 KiB
Markdown
59 lines
2.1 KiB
Markdown
## Context
|
|
|
|
Currently, the application crashes with cryptic SQLAlchemy errors when:
|
|
1. Database tables don't exist (fresh deployment)
|
|
2. Migrations haven't been applied
|
|
3. 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
|
|
|
|
1. **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.
|
|
|
|
2. **Use alembic programmatic API**
|
|
- Rationale: Avoids subprocess calls and captures errors properly
|
|
- Run via `alembic.command.upgrade()` in async context
|
|
|
|
3. **Add connection retry with backoff**
|
|
- Rationale: Database may not be ready when app starts
|
|
- 5 retries with 2-second exponential backoff
|
|
|
|
4. **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
|
|
|
|
1. Add `init_database()` function that runs migrations and seed data
|
|
2. Modify startup event to call `init_database()` with retries
|
|
3. Update Docker CMD to ensure database is ready
|
|
4. Test with fresh database volume
|
|
|
|
## Open Questions
|
|
|
|
- Should we add a separate `db init` CLI command for manual runs?
|
|
- Do we need database connection pooling configuration?
|