From 8cc9c88ff56a116c8e6d9400ba5f069213ecdaa5 Mon Sep 17 00:00:00 2001
From: jross <jake.ross@nmt.edu>
Date: Tue, 7 Jul 2026 15:12:38 -0600
Subject: [PATCH] fix(api): probe the database in /health so a 200 proves
 PostGIS is reachable

/health previously returned {"status": "ok", "version": ...} without touching
the database, so a 200 only proved the process was up -- an uptime monitor or
status page could report green while PostGIS was unreachable. Add a lightweight
SELECT 1 ping: on success return db=ok (200); on failure return
status=degraded, db=error with a 503 so monitors flag the outage. The route is
now sync so the sync SQLAlchemy session runs in the threadpool rather than
blocking the event loop.

Tests: happy path (200, db=ok, version present) and DB-down via dependency
override (503, degraded, db=error).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 core/app.py          | 27 ++++++++++++++++++++++---
 tests/test_health.py | 48 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_health.py

diff --git a/core/app.py b/core/app.py
index 6ee7ad992..d14ccecf3 100644
--- a/core/app.py
+++ b/core/app.py
@@ -20,13 +20,17 @@
 from contextlib import asynccontextmanager
 from typing import AsyncGenerator
 
-from fastapi import FastAPI
+from fastapi import Depends, FastAPI, Response, status
 from fastapi import Request
 from fastapi.openapi.docs import (
     get_swagger_ui_html,
     get_swagger_ui_oauth2_redirect_html,
 )
 from fastapi.openapi.utils import get_openapi
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+from db.engine import get_db_session
 
 from .settings import settings
 
@@ -221,8 +225,25 @@ async def warmup():
 
     @app.get("/health", tags=["meta"])
     @public_route
-    async def health():
-        return {"status": "ok", "version": settings.version}
+    def health(response: Response, session: Session = Depends(get_db_session)):
+        # Ping the database so a 200 actually proves PostGIS is reachable, not
+        # just that the process is up. Uptime monitors / status pages assert on
+        # the "db" field; on failure return 503 so they flag the outage.
+        try:
+            session.execute(text("SELECT 1"))
+            db_ok = True
+        except Exception:
+            logger.exception("health check: database ping failed")
+            db_ok = False
+
+        if not db_ok:
+            response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+
+        return {
+            "status": "ok" if db_ok else "degraded",
+            "db": "ok" if db_ok else "error",
+            "version": settings.version,
+        }
 
     return app
 
diff --git a/tests/test_health.py b/tests/test_health.py
new file mode 100644
index 000000000..ef8758d8c
--- /dev/null
+++ b/tests/test_health.py
@@ -0,0 +1,48 @@
+# ===============================================================================
+# Copyright 2025 ross
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ===============================================================================
+from db.engine import get_db_session
+from tests import client
+
+
+def test_health_ok():
+    """A healthy service pings the DB and reports db=ok with a 200."""
+    response = client.get("/health")
+    assert response.status_code == 200
+    body = response.json()
+    assert body["status"] == "ok"
+    assert body["db"] == "ok"
+    assert "version" in body
+
+
+def test_health_db_down_returns_503():
+    """When the DB ping fails, /health returns 503 and reports db=error."""
+
+    class _BadSession:
+        def execute(self, *args, **kwargs):
+            raise Exception("simulated database outage")
+
+    def _bad_session():
+        yield _BadSession()
+
+    client.app.dependency_overrides[get_db_session] = _bad_session
+    try:
+        response = client.get("/health")
+        assert response.status_code == 503
+        body = response.json()
+        assert body["status"] == "degraded"
+        assert body["db"] == "error"
+    finally:
+        client.app.dependency_overrides.pop(get_db_session, None)