Enhanced Database Health Check Metadata Display

[lbedner]

Goal

Enhance database health check to collect and display more detailed metadata including database engine type, version, and connection details in the
frontend health display.

Background

Currently, the database health check provides basic metadata (implementation, url, database_exists, engine_echo), but users need more detailed
information about their database for better observability and debugging.

Implementation

Enhance Database Health Check Metadata Collection

• Collect database engine version information
• Add database file size for SQLite databases
• Include connection pool statistics when available
• Add more detailed engine information (SQLite version, file path resolution, etc.)
• Maintain backward compatibility with existing metadata structure

Update Frontend Display (if needed)

• Ensure enhanced metadata displays properly in health CLI output
• Format database-specific details in a user-friendly way
• Handle missing metadata gracefully

Follow Existing Patterns

• Use existing health check metadata patterns from worker/cache components
• Maintain consistent error handling and status determination
• Ensure all metadata is JSON-serializable for API responses

Files Modified

• aegis/templates/.../app/services/system/health.py.j2 — Enhance check_database_health() metadata collection
• aegis/templates/.../app/cli/health_display.py.j2 — Update display formatting (if customization needed)

Enhanced Metadata Implementation

Additional metadata to collect:

metadata = {
"implementation": "sqlite", # existing
"url": settings.DATABASE_URL, # existing
"database_exists": True, # existing
"engine_echo": settings.DATABASE_ENGINE_ECHO, # existing
# NEW METADATA:
"version": "3.43.0", # SQLite version
"file_size_bytes": 8192, # For SQLite files
"file_size_human": "8.0 KB", # Human readable
"connection_pool_size": 5, # If applicable
"pragma_settings": {...}, # Key SQLite settings
"wal_enabled": False, # Write-Ahead Logging status
}

Testing

• Unit tests: Enhanced metadata collection works correctly
• Template tests: Generated health checks include enhanced metadata when database component selected
• Integration tests: Frontend displays enhanced metadata properly
• Error handling: Graceful fallback when metadata unavailable

Success Criteria

• Database engine version displayed in health output
• SQLite file size shown when available
• Connection details properly formatted
• All existing functionality preserved
• Enhanced metadata helps with debugging and monitoring
• Frontend health display shows enhanced information clearly

Acceptance Criteria

1. curl http://localhost:8000/health/detailed shows enhanced database metadata
2. CLI health command displays database version and file details
3. All database health tests continue to pass
4. Enhanced metadata appears only when database component is selected
5. Graceful handling when enhanced metadata unavailable