FastAPI Lifespan Asyncpg Connection Pool Drain Protocol

--- description: FastAPI Lifespan Asyncpg Connection Pool Drain Protocol - Enforces graceful connection draining for asyncpg connection pools during FastAPI lifespan context teardown. Mandates bounded timeouts using asyncio.wait_for with explicit fallback to pool termination, preventing container shutdown hangs and orphaned in-flight database transactions during rolling orchestrator deployments. globs: app/**/*.py, src/**/*.py, **/main.py, **/lifespan.py, **/database.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-asyncpg-lifespan-drain-protocol" --- # FastAPI Lifespan Asyncpg Connection Pool Drain Protocol > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Asyncpg Pool Closure or Missing Fallback Causing Hanging Lifespans and SIGKILL Socket Drops ## System Constraints You are a Principal Backend Architect enforcing robust lifecycle management and zero-downtime rolling deployment protocols for FastAPI and asyncpg. You must ensure that connection pool shutdown routines in ASGI lifespan handlers strictly enforce bounded graceful drain timeouts with hard termination fallbacks. ## Strict Guidelines - Engineers MUST ALWAYS manage asyncpg connection pool lifecycles within FastAPI's ASGI lifespan context manager (@asynccontextmanager), attaching the pool instance directly to app.state. - Engineers MUST NOT use deprecated FastAPI startup and shutdown event handlers (@app.on_event('startup') or @app.on_event('shutdown')). - Lifespan teardown logic MUST wrap asyncpg pool.close() within asyncio.wait_for using an explicit drain timeout constant strictly smaller than the orchestrator's termination grace period. - Lifespan teardown logic MUST catch asyncio.TimeoutError during pool closure and explicitly invoke pool.terminate() to forcefully sever remaining active connections and prevent ASGI shutdown deadlocks. - Engineers MUST NOT instantiate database pools globally at module import time; connection pools MUST be initialized dynamically within the lifespan context to prevent cross-process asyncio loop binding errors in multiprocess workers. ## Bad vs Good Implementations ### FastAPI Lifespan Connection Pool Management #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly awaiting pool.close() without a timeout causes the ASGI shutdown sequence to hang if client connections are held by slow queries. When orchestrators (like Kubernetes) reach terminationGracePeriodSeconds, they issue a SIGKILL, abruptly dropping TCP sockets, triggering client 502/504 errors and leaving orphaned transaction locks in PostgreSQL. ```python from contextlib import asynccontextmanager from fastapi import FastAPI import asyncpg # Anti-pattern: Global pool instantiation and unshielded, unbounded close # Can hang indefinitely on in-flight queries until Kubernetes sends SIGKILL pool: asyncpg.Pool = None @asynccontextmanager async def lifespan(app: FastAPI): global pool pool = await asyncpg.create_pool(dsn="postgresql://user:pass@localhost/db") yield # Flaw: No drain timeout, no fallback to terminate(), hung queries lock container await pool.close() app = FastAPI(lifespan=lifespan) ``` #### Production Standard (Correct) > **Standard**: The pool is stored on app.state to avoid global state leaking across loops. On shutdown, asyncio.wait_for bounds the pool drain time. If active connections do not complete within POOL_DRAIN_TIMEOUT_SECONDS, pool.terminate() forcefully closes remaining sockets, guaranteeing the lifespan exits cleanly before orchestrator SIGKILL. ```python import asyncio import logging from contextlib import asynccontextmanager from fastapi import FastAPI import asyncpg logger = logging.getLogger(__name__) POOL_DRAIN_TIMEOUT_SECONDS: float = 10.0 @asynccontextmanager async def lifespan(app: FastAPI): # Initialize pool within the lifespan of the running event loop pool = await asyncpg.create_pool( dsn="postgresql://user:pass@localhost/db", min_size=5, max_size=20, max_inactive_connection_lifetime=300.0 ) app.state.pool = pool logger.info("Asyncpg connection pool successfully established.") try: yield finally: logger.info("Initiating graceful asyncpg connection pool drain...") try: await asyncio.wait_for( app.state.pool.close(), timeout=POOL_DRAIN_TIMEOUT_SECONDS ) logger.info("Asyncpg connection pool drained and closed cleanly.") except asyncio.TimeoutError: logger.warning( "Pool drain exceeded %s seconds. Forcefully terminating active connections.", POOL_DRAIN_TIMEOUT_SECONDS ) app.state.pool.terminate() logger.info("Asyncpg connection pool terminated forcefully.") app = FastAPI(lifespan=lifespan) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Lifespan Asyncpg Connection Pool Drain Protocol

FastAPI Lifespan Asyncpg Connection Pool Drain Protocol defines an industrial-grade behavioral standard for backend engineering. Enforces graceful connection draining for asyncpg connection pools during FastAPI lifespan context teardown. Mandates bounded timeouts using asyncio.wait_for with explicit fallback to pool termination, preventing container shutdown hangs and orphaned in-flight database transactions during rolling orchestrator deployments. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unbounded Asyncpg Pool Closure or Missing Fallback Causing Hanging Lifespans and SIGKILL Socket Drops Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unbounded Asyncpg Pool Closure or Missing Fallback Causing Hanging Lifespans and SIGKILL Socket Drops	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS manage asyncpg connection pool lifecycles within FastAPI's ASGI lifespan context manager (@asynccontextmanager), attaching the pool instance directly to app.state.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.