fix(api): probe database in /health so 200 proves PostGIS reachable

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
 

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)