All Stories
2-2-pgbouncer-connection-pooling-setupDoneEpic 2.2
Story 2.2: PgBouncer Connection Pooling Setup
Status: done
Tasks
- Task 1: Supabase Supavisor Configuration (AC: #1, #2) - SIMPLIFIED
- 1.1: Configure PGBOUNCER_URL detection in database.py
- 1.2: Auto-detect Supavisor from port 6543 or pooler.supabase hostname
- 1.3: Disable statement caching when PgBouncer detected (statement_cache_size=0)
- 1.4: Adjust local pool size (5-20 connections when using pooler vs 10-50 direct)
- Task 2: Application Connection Migration (AC: #3)
- 2.1: Add PGBOUNCER_URL environment variable support to database.py
- 2.2: PGBOUNCER_URL takes precedence over DATABASE_URL
- 2.3: Fallback to direct DATABASE_URL if PGBOUNCER_URL not set
- 2.4: Test backward compatibility with existing configuration
- Task 3: Graceful Degradation (AC: #5)
- 3.1: Implement `with_retry()` function with exponential backoff (3 retries, 0.1-2.0s delays)
- 3.2: Add `PoolExhaustedError` exception class
- 3.3: Add `acquire_with_fallback()` context manager with timeout handling
- 3.4: Create global exception handler returning 503 with Retry-After header
- Task 4: Metrics and Monitoring (AC: #4)
- 4.1: Add `is_pgbouncer` and `free_size` to pool stats
- 4.2: Pool stats now include utilization percentage
- 4.3: Structured logging for pool saturation events
- Task 5: Health Check Updates (AC: #6)
- 5.1: Add `get_pool_health()` method with threshold logic
- 5.2: Health status: "healthy" (<75%), "warning" (75-89%), "critical" (>=90%)
- 5.3: `/health` endpoint includes `database_pool_health` with thresholds
- 5.4: `/health/db` endpoint includes pool health details
- Task 6: Testing and Validation (AC: #1-6)
- 6.1: 22 unit tests covering all functionality
- 6.2: PgBouncer detection tests (PGBOUNCER_URL, port 6543, pooler.supabase)
- 6.3: Pool health threshold tests (74%, 75%, 89%, 90%, 100%)
- 6.4: Retry with backoff tests (success, retry, exhaustion)
- 6.5: Load testing with Locust (deferred to story 2-6)
Progress
Tasks6/6
Acceptance Criteria0
Total Tasks6