headquarter/openspec/changes/database-setup-recovery/specs/database-initialization/spec.md at ea6c466c6c676249b8d678f269e4afeabdd5082f

Files

T

Fusion ea6c466c6c feat: add automatic database initialization and recovery

- 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)

2026-05-18 22:10:15 +02:00

1.9 KiB

Raw Blame History

ADDED Requirements

Requirement: Automatic Database Initialization

The system SHALL automatically initialize the database on application startup.

Scenario: Fresh database

GIVEN a new database with no tables
WHEN the application starts
THEN it runs all pending migrations
AND creates all required tables
AND seeds built-in data
AND starts accepting requests

Scenario: Database with existing migrations

GIVEN a database with some migrations applied
WHEN the application starts
THEN it runs only pending migrations
AND does not re-run existing migrations

Requirement: Database Connection Resilience

The system SHALL retry database connections during startup.

Scenario: Database not ready

GIVEN the database is not yet accepting connections
WHEN the application starts
THEN it retries the connection 5 times
AND waits 2 seconds between retries
AND fails gracefully with a clear error message

Scenario: Database connection refused

GIVEN the database is unreachable
WHEN the application starts
THEN it logs a clear error: "Database connection failed"
AND exits with a non-zero status code

Requirement: Seed Data Management

The system SHALL handle seed data after migrations complete.

Scenario: Seed after migrations

GIVEN migrations have just been applied
WHEN seeding built-in tool types
THEN the seeding only runs after migrations succeed
AND handles missing tables gracefully

Requirement: Startup Error Messages

The system SHALL provide clear error messages for common database issues.

Scenario: Missing migrations

GIVEN tables are missing because migrations haven't run
WHEN the application starts
THEN the error message indicates: "Database not initialized. Run migrations."

Scenario: Authentication failure

GIVEN database credentials are wrong
WHEN the application starts
THEN the error message indicates: "Database authentication failed"

1.9 KiB Raw Blame History