Add Database Prefer Mode

Summary

Implement the "prefer mode" detection and fallback logic for the Container Registry's database.enabled configuration as outlined in Epic &19638.

Background

With the database.enabled field now supporting string values ("true", "false", "prefer"), the Container Registry needs to implement the intelligent detection logic for the "prefer" mode that:

• Detects fresh vs. existing installations
• Automatically selects the appropriate metadata storage method
• Provides graceful fallback behavior

Implementation

Add the "prefer mode" logic that:

• Fresh installs: Attempts database connection first, falls back to legacy metadata if database is unavailable or not configured
• Existing installs: Detects previous metadata storage method and continues using it
• Error handling: Graceful fallback with appropriate logging when database connection fails in prefer mode
• Detection logic: Extends existing installation history detection capabilities

Success Criteria

• database.enabled: "prefer" intelligently selects metadata storage method
• Fresh installs default to database metadata when available
• Existing installs continue with their current metadata method
• Graceful fallback to legacy metadata when database unavailable
• Clear logging indicates mode selection decisions and reasoning
• Comprehensive test coverage for all prefer mode scenarios

This feature enables the Container Registry to automatically provide the best metadata storage experience based on installation context while maintaining backward compatibility and stability.

Flow Diagrams for Each Configuration

Note: These are not the actual control flow, but are intended to represent an idealized decision tree for each of the three configuration options.

Database Enabled = true

flowchart TD
    A[Registry Starts with database.enabled = true] --> B{Check filesystem lockfile}
    B -->|Found| C[Legacy metadata detected]
    C --> D[Error: Cannot use database with existing filesystem metadata]
    D --> E[FAIL: registry filesystem metadata in use, please import data before enabling the database]
    
    B -->|Not found| F{Check database lockfile}
    F -->|Found| G[Database metadata detected]
    F -->|Not found| H[Fresh install detected]
    
    G --> I{Database configured?}
    H --> I
    I -->|Yes| J[Test database connection]
    I -->|No| K[FAIL: Database required but not configured]
    
    J -->|Success| L{Pending migrations?}
    J -->|Fail| M[FAIL: Database connection failed]
    
    L -->|Yes| N[FAIL: there are pending database migrations, use 'registry database migrate' CLI command]
    L -->|No| O[Create/update database lockfile]
    O --> P[Start registry with database metadata]
    
    style H fill:#e1f5fe
    style G fill:#e8f5e8
    style C fill:#fff3e0
    style P fill:#c8e6c9
    style D fill:#ffcdd2
    style E fill:#ffcdd2
    style K fill:#ffcdd2
    style M fill:#ffcdd2
    style N fill:#ffcdd2

Database Enabled = false

flowchart TD
    A[Registry Starts with database.enabled = false] --> B{Check database lockfile}
    B -->|Found| C[FAIL: Cannot disable database with existing database metadata]
    
    B -->|Not found| D{Check filesystem lockfile}
    D -->|Found| E[Start registry with filesystem metadata]
    D -->|Not found| F[Enumerate repositories in filesystem]
    
    F --> G{Repositories found?}
    G -->|Yes| H[Create filesystem lockfile]
    G -->|No| I[No lockfile created]
    G -->|Error| J[FAIL: Could not enumerate repositories]
    
    H --> E
    I --> E
    
    %% Styling
    style E fill:#c8e6c9
    style C fill:#ffcdd2
    style J fill:#ffcdd2

Database Enabled = prefer

flowchart TD
    A[Registry Starts with database.enabled = prefer] --> B{Check filesystem lockfile}
    B -->|Found| C[Legacy metadata detected]
    C --> D{Database lockfile exists?}
    D -->|Yes| E[Error: Conflicting lockfiles]
    E --> F[FAIL: Manual intervention required]
    D -->|No| G[Continue with filesystem metadata]
    G --> H[Start registry with filesystem metadata]
    
    B -->|Not found| I{Check database lockfile}
    I -->|Found| J[Database metadata detected]
    I -->|Not found| K[Fresh install detected]
    
    J --> L{Database configured?}
    K --> M{Database configured?}
    
    L -->|Yes| N[Test database connection]
    L -->|No| O[FAIL: Database required but not configured]
    
    M -->|Yes| P[Test database connection]
    M -->|No| Q[FAIL: Fresh install requires database in prefer mode]
    
    N -->|Success| R{Pending migrations?}
    N -->|Fail| S[FAIL: Database connection failed]
    
    P -->|Success| T{Pending migrations?}
    P -->|Fail| U[FAIL: Database connection failed]
    
    R -->|Yes| V[FAIL: there are pending database migrations, use 'registry database migrate' CLI command]
    R -->|No| W[Start registry with database metadata]
    
    T -->|Yes| X[FAIL: there are pending database migrations, use 'registry database migrate' CLI command]
    T -->|No| Y[Create database lockfile]
    Y --> Z[Start registry with database metadata]

    style K fill:#e1f5fe
    style J fill:#e8f5e8
    style C fill:#fff3e0
    style W fill:#c8e6c9
    style Z fill:#c8e6c9
    style H fill:#c8e6c9
    style E fill:#ffcdd2
    style F fill:#ffcdd2
    style O fill:#ffcdd2
    style Q fill:#ffcdd2
    style S fill:#ffcdd2
    style U fill:#ffcdd2
    style V fill:#ffcdd2
    style X fill:#ffcdd2