headquarter/openspec/changes/archive/2026-05-18-database-setup-recovery/specs/database-initialization/spec.md

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"