Improve backend and database connectivity error handling

Backend:
- Add ping() to IDatabaseAdapter for isolated connectivity testing (MySQL + Postgres)
- Refactor handleHealth: explicit connectivity test before schema/data queries
- Return status "error" with dbStatus ("db_unreachable" / "schema_mismatch") and dbError
- Auto-initialize database in health handler when DB becomes reachable after outage
- Add periodic 30s DB liveness ping with edge-triggered logging (state transitions only)
- Strip stack traces from user-facing db_unreachable error messages

Frontend:
- Show "Server Unreachable" error card (not permanent spinner) when backend is down at startup
- Show "Connection Error" with DB details when health reports db_unreachable
- Reorder health checks: status "error" before !initialized so db_unreachable is caught
- BackendDisconnectedDialog poll now detects db_unreachable and shows DB error detail
- Fix spinner centering by removing hardcoded width/height from progressIndicatorCard
- Fix shouldComponentUpdate to include backendUnreachable and startupError
- Replace unnecessary setStatePromise with setState where immediate return follows
- Change "Backend connection restored" toast from error to info

Signed-off-by: Mike Lischke <mike@lischke-online.de>

Author: mike-lischke

src/App.scss

@@ -135,10 +135,57 @@ h6 {
     display: flex;
     justify-content: center;
     align-items: center;
-    width: 180px;
-    height: 180px;
     background: var(--color-base-100);
-    border-radius: 12px;
+    border-radius: 1rem;
+}
+
+.backend-unreachable-card {
+    background: var(--color-base-200);
+    z-index: 9999;
+}
+
+.backend-unreachable-content {
+    text-align: center;
+    max-width: 420px;
+    padding: 2rem;
+    background: var(--color-base-100);
+    border-radius: 1rem;
+    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.3);
+
+    h2 {
+        margin: 0 0 0.75rem 0;
+        font-size: 1.5rem;
+        color: var(--color-error);
+    }
+
+    p {
+        margin: 0 0 1.5rem 0;
+        line-height: 1.6;
+        color: var(--color-base-content);
+    }
+
+    .startup-error-message {
+        margin: 0 0 1.5rem 0;
+        padding: 0.75rem 1rem;
+        background: var(--color-base-200);
+        border-radius: 0.5rem;
+        font-family: monospace;
+        font-size: 0.875rem;
+        line-height: 1.5;
+        white-space: pre-wrap;
+        word-break: break-word;
+        color: var(--color-error);
+        text-align: left;
+    }
+
+    button {
+        min-width: 120px;
+    }
+}
+
+.backend-unreachable-icon {
+    font-size: 3rem;
+    margin-bottom: 0.75rem;
 }
 
 #wrapper {

src/App.tsx

@@ -113,6 +113,12 @@ interface IAppState {
     printOptions?: IPrintOptions;
 
     instrumentEditorEnabled: boolean;
+
+    /** When true, the backend health endpoint was unreachable. */
+    backendUnreachable: boolean;
+
+    /** Error message shown during startup when the backend or database is unreachable. */
+    startupError?: string;
 }
 
 export class App extends UIComponent<{}, IAppState> {
@@ -160,6 +166,7 @@ export class App extends UIComponent<{}, IAppState> {
             headerPinned: false,
             printing: false,
             instrumentEditorEnabled: false,
+            backendUnreachable: false,
         };
 
         const selectionManager = new SelectionManager();
@@ -188,12 +195,15 @@ export class App extends UIComponent<{}, IAppState> {
     }
 
     public override shouldComponentUpdate(nextProps: {}, nextState: IAppState): boolean {
-        const { displayMode, sidebarOpen, phase, headerPinned, printing } = this.state;
+        const { displayMode, sidebarOpen, phase, headerPinned, printing, backendUnreachable,
+            startupError } = this.state;
 
         return displayMode !== nextState.displayMode
             || sidebarOpen !== nextState.sidebarOpen || phase !== nextState.phase
             || headerPinned !== nextState.headerPinned
-            || printing !== nextState.printing;
+            || printing !== nextState.printing
+            || backendUnreachable !== nextState.backendUnreachable
+            || startupError !== nextState.startupError;
     }
 
     public override componentDidUpdate(_prevProps: {}, prevState: IAppState): void {
@@ -220,7 +230,7 @@ export class App extends UIComponent<{}, IAppState> {
 
     public render() {
         const { phase, displayMode, sidebarOpen, headerPinned, instrumentEditorEnabled, printing,
-            printOptions } = this.state;
+            printOptions, backendUnreachable, startupError } = this.state;
         const isRunning = phase === AppPhase.Running;
 
         let splashContent: ComponentChild;
@@ -321,6 +331,24 @@ export class App extends UIComponent<{}, IAppState> {
             </Button>;
         }
 
+        let checkingContent: ComponentChild;
+        if (phase === AppPhase.Checking) {
+            if (backendUnreachable) {
+                checkingContent = this.renderBackendUnreachable();
+            } else if (startupError) {
+                checkingContent = this.renderStartupError(startupError);
+            } else {
+                checkingContent = (
+                    <div className="progressIndicatorCard" style={{
+                        position: "fixed", inset: 0, display: "flex",
+                        justifyContent: "center", alignItems: "center",
+                    }}>
+                        <ProgressIndicator />
+                    </div>
+                );
+            }
+        }
+
         return (
             <>
                 {isRunning && (
@@ -550,14 +578,7 @@ export class App extends UIComponent<{}, IAppState> {
 
                 <ConfirmDialog ref={this.confirmDialogRef} />
 
-                {phase === AppPhase.Checking && (
-                    <div className="progressIndicatorCard" style={{
-                        position: "fixed", inset: 0, display: "flex",
-                        justifyContent: "center", alignItems: "center",
-                    }}>
-                        <ProgressIndicator />
-                    </div>
-                )}
+                {checkingContent}
 
                 <Container
                     id="splashScreen"
@@ -574,15 +595,58 @@ export class App extends UIComponent<{}, IAppState> {
     }
 
     /**
-     * Checks if the backend is reachable and initialised. If not, opens the setup dialog.
-     * Once the backend is ready, proceeds with data model initialisation.
-     *
-     * @returns A promise that resolves when the check is complete.
+     * Retries the backend health check after a connection failure.
      */
+    private handleRetryConnection = (): void => {
+        void this.setStatePromise({ backendUnreachable: false, startupError: undefined }).then(() => {
+            return this.checkBackendThenInitialize();
+        });
+    };
+
+    private renderBackendUnreachable(): ComponentChild {
+        return (
+            <div className="backend-unreachable-card" style={{
+                position: "fixed", inset: 0, display: "flex",
+                flexDirection: "column", justifyContent: "center", alignItems: "center",
+            }}>
+                <div className="backend-unreachable-content">
+                    <div className="backend-unreachable-icon">⚠️</div>
+                    <h2>Server Unreachable</h2>
+                    <p>
+                        The Animada Score Book server could not be reached.
+                        Make sure the backend is running and try again.
+                    </p>
+                    <button className="du-btn du-btn-primary" onClick={this.handleRetryConnection}>
+                        Retry
+                    </button>
+                </div>
+            </div>
+        );
+    }
+
+    private renderStartupError(error: string): ComponentChild {
+        return (
+            <div className="backend-unreachable-card" style={{
+                position: "fixed", inset: 0, display: "flex",
+                flexDirection: "column", justifyContent: "center", alignItems: "center",
+            }}>
+                <div className="backend-unreachable-content">
+                    <div className="backend-unreachable-icon">⚠️</div>
+                    <h2>Connection Error</h2>
+                    <pre className="startup-error-message">{error}</pre>
+                    <button className="du-btn du-btn-primary" onClick={this.handleRetryConnection}>
+                        Retry
+                    </button>
+                </div>
+            </div>
+        );
+    }
+
     private async checkBackendThenInitialize(): Promise<void> {
         let health: {
             status: string; configLoaded: boolean; configError?: string;
-            initialized: boolean; hasUsers: boolean; dbError?: string;
+            initialized: boolean; hasUsers: boolean; dbStatus?: string; dbError?: string;
+            engine?: string; host?: string; port?: number; database?: string;
         } | undefined;
 
         try {
@@ -593,7 +657,8 @@ export class App extends UIComponent<{}, IAppState> {
         }
 
         if (!health) {
-            // Backend not reachable — handled by the splash screen with a progress indicator.
+            this.setState({ backendUnreachable: true });
+
             return;
         }
 
@@ -607,6 +672,23 @@ export class App extends UIComponent<{}, IAppState> {
             return;
         }
 
+        if (health.status === "error") {
+            const { dbStatus, dbError: errorMsg, engine, host, port, database } = health;
+
+            if (dbStatus === "db_unreachable") {
+                const connectionInfo = `${engine}://${host}:${port ?? ""}/${database ?? ""}`;
+                this.setState({
+                    startupError: `${errorMsg ?? "Database unreachable"}\n\n`
+                        + `Connection: ${connectionInfo}\n`
+                        + "Is the database server running and is the IP address correct?",
+                });
+
+                return;
+            }
+
+            // Schema mismatch — fall through to the dbError path below.
+        }
+
         if (!health.initialized) {
             await this.setStatePromise({ phase: AppPhase.Setup });
             await this.backendSetupDialogRef.current?.show({

src/server/Router.ts

@@ -353,44 +353,130 @@ export class Router {
             return;
         }
 
-        let hasData = false;
-        let anyUsers = false;
-        let dbError: string | undefined;
+        if (!this.auth.adapter.isInitialized()) {
+            // Pool not created yet — the backend may have failed to auto-connect or
+            // is waiting for first-time setup. Test connectivity to distinguish the two.
+            const connResult = await this.auth.adapter.testConnection(this.config.database);
+
+            if (!connResult.success) {
+                this.ctx.sendJson(res, {
+                    status: "error",
+                    dbStatus: "db_unreachable",
+                    dbError: `Database unreachable: ${connResult.error ?? "unknown reason"}`,
+                    configLoaded: true,
+                    initialized: false,
+                    engine: this.config.database.engine,
+                    host: this.config.database.host,
+                    port: this.config.database.port,
+                    database: this.config.database.database,
+                    hasData: false,
+                    hasUsers: false,
+                });
 
-        if (this.auth.adapter.isInitialized()) {
-            const dbVersion = await this.auth.adapter.getSchemaVersion();
-
-            if (dbVersion === 0) {
-                dbError = "Database schema is from an older version without version tracking. "
-                    + "A reset is required.";
-            } else if (dbVersion < schemaVersion) {
-                dbError = `Database schema is version ${dbVersion}, `
-                    + `but version ${schemaVersion} is required. Use Reset Database to upgrade.`;
+                return;
             }
 
-            // Always query actual data counts so the frontend can show the correct confirmation dialog.
+            // DB server is reachable — try to auto-initialise so the backend
+            // self-heals when the database becomes available after a temporary outage.
             try {
+                await this.auth.adapter.initialize(this.config.database);
+
+                const { engine, host, port, database } = this.config.database;
+                console.log(
+                    `Backend initialised via health check: ${engine} @ ${host}:${port}/${database}`,
+                );
+
+                // Run the same seeding as normal startup (idempotent — seed only if empty,
+                // anonymous user only if missing).
                 const rows = await this.auth.adapter.query<{ cnt: number; }>(
                     "SELECT COUNT(*) AS cnt FROM folders",
                 );
 
-                hasData = (rows[0]?.cnt ?? 0) > 0;
-                anyUsers = await this.auth.hasUsers();
+                if ((rows[0]?.cnt ?? 0) === 0) {
+                    await this.seedIfExists(this.auth.adapter);
+                }
+
+                await this.seedAnonymousUser(this.auth.adapter);
+
+                // Fall through to the normal health path below (pool is now ready).
             } catch (e) {
-                dbError = `Schema check failed: ${convertErrorToString(e)}`;
+                this.ctx.sendJson(res, {
+                    status: "error",
+                    dbStatus: "db_unreachable",
+                    dbError: `Database initialisation failed: ${(e as Error).message}`,
+                    configLoaded: true,
+                    initialized: false,
+                    engine: this.config.database.engine,
+                    host: this.config.database.host,
+                    port: this.config.database.port,
+                    database: this.config.database.database,
+                    hasData: false,
+                    hasUsers: false,
+                });
+
+                return;
             }
         }
 
+        // Isolated infrastructure check — a lightweight SELECT 1 on the existing pool.
+        // If this fails we know it is a connectivity problem, not a schema or data issue.
+        try {
+            await this.auth.adapter.ping();
+        } catch (e) {
+            this.ctx.sendJson(res, {
+                status: "error",
+                dbStatus: "db_unreachable",
+                dbError: `Database unreachable: ${(e as Error).message}`,
+                configLoaded: true,
+                initialized: true,
+                engine: this.config.database.engine,
+                host: this.config.database.host,
+                port: this.config.database.port,
+                database: this.config.database.database,
+                hasData: false,
+                hasUsers: false,
+            });
+
+            return;
+        }
+
+        // Connectivity is confirmed — schema and data queries are trusted to produce
+        // meaningful errors if they fail.
+        let hasData = false;
+        let anyUsers = false;
+        let dbError: string | undefined;
+        let dbStatus: string | undefined;
+
+        const dbVersion = await this.auth.adapter.getSchemaVersion();
+
+        if (dbVersion === 0) {
+            dbStatus = "schema_mismatch";
+            dbError = "Database schema is from an older version without version tracking. "
+                + "A reset is required.";
+        } else if (dbVersion < schemaVersion) {
+            dbStatus = "schema_mismatch";
+            dbError = `Database schema is version ${dbVersion}, `
+                + `but version ${schemaVersion} is required. Use Reset Database to upgrade.`;
+        }
+
+        const rows = await this.auth.adapter.query<{ cnt: number; }>(
+            "SELECT COUNT(*) AS cnt FROM folders",
+        );
+
+        hasData = (rows[0]?.cnt ?? 0) > 0;
+        anyUsers = await this.auth.hasUsers();
+
         this.ctx.sendJson(res, {
-            status: "ok",
+            status: dbStatus ? "error" : "ok",
             configLoaded: true,
-            initialized: this.auth.adapter.isInitialized(),
+            initialized: true,
             engine: this.config.database.engine,
             host: this.config.database.host,
             port: this.config.database.port,
             database: this.config.database.database,
             hasData,
             hasUsers: anyUsers,
+            dbStatus,
             dbError,
         });
     };