From 5b0036b644f30347029bdac5009ed54da4fffcb0 Mon Sep 17 00:00:00 2001 From: Leo Miranda Date: Fri, 23 Jan 2026 16:34:13 +0000 Subject: [PATCH] Add "sprint-9-10-graceful-error-handling" --- sprint-9-10-graceful-error-handling.-.md | 36 ++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 sprint-9-10-graceful-error-handling.-.md diff --git a/sprint-9-10-graceful-error-handling.-.md b/sprint-9-10-graceful-error-handling.-.md new file mode 100644 index 0000000..e46ee9a --- /dev/null +++ b/sprint-9-10-graceful-error-handling.-.md @@ -0,0 +1,36 @@ +# Sprint 9-10 - Graceful Error Handling in Service Layers + +**Date**: 2026-01-17 +**Tags**: python, postgresql, service-layer, error-handling, dash, graceful-degradation, arm64 + +--- + +## Context +Building the Toronto Neighbourhood Dashboard with a service layer that queries PostgreSQL/PostGIS dbt marts to provide data to Dash callbacks. + +## Problem +Initial service layer implementation let database connection errors propagate as unhandled exceptions. When the PostGIS Docker container was unavailable (common on ARM64 systems where the x86_64 image fails), the entire dashboard would crash instead of gracefully degrading. + +## Solution +Wrapped database queries in try/except blocks to return empty DataFrames/lists/dicts when the database is unavailable: + +```python +def _execute_query(sql: str, params: dict | None = None) -> pd.DataFrame: + try: + engine = get_engine() + with engine.connect() as conn: + return pd.read_sql(text(sql), conn, params=params) + except Exception: + return pd.DataFrame() +``` + +This allows: +1. Dashboard to load and display empty states +2. Development/testing without running database +3. Graceful degradation in production + +## Prevention +- **Always design service layers with graceful degradation** - assume external dependencies can fail +- **Return empty collections, not exceptions** - let UI components handle empty states +- **Test without database** - verify the app doesn't crash when DB is unavailable +- **Consider ARM64 compatibility** - PostGIS images may not support all platforms