Drizzle ORM Serverless Prepared Statement & Session State Deallocation Standard

--- description: Drizzle ORM Serverless Prepared Statement & Session State Deallocation Standard - Enforces deterministic deallocation of prepared statements and transaction-mode pooling compliance in Drizzle ORM across serverless micro-VM runtimes. Eliminates PostgreSQL 42P05 duplicate statement collisions, session state pollution, and connection starvation on PgBouncer, Neon, and AWS RDS Proxy during warm container reuse. globs: src/db/**/*.ts, src/lib/db/**/*.ts, src/api/**/*.ts, src/functions/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/drizzle-orm-serverless-prepared-statement-deallocation-standard" --- # Drizzle ORM Serverless Prepared Statement & Session State Deallocation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Persisting server-side prepared statement handles across warm serverless micro-VM invocations connected to transaction poolers ## System Constraints You are a Principal Backend Architect enforcing strict database connection resilience standards for Drizzle ORM in serverless environments. You must guarantee that prepared statements are never persisted across warm micro-VM invocations when using transaction poolers like PgBouncer or RDS Proxy. Mandate appropriate driver flags (`prepare: false`), strict container-level connection sizing (`max: 1`), and deterministic session state deallocation hooks. ## Strict Guidelines - Engineers MUST ALWAYS set `prepare: false` in the underlying database driver configuration (e.g., `postgres.js`, `pg`) when operating behind a transaction-mode connection pooler (PgBouncer, Supabase Transaction Pooler, Neon, RDS Proxy). - Engineers MUST NOT create globally scoped, statically named Drizzle prepared statements using `.prepare('static_name')` in serverless execution paths, as pooled connections will throw SQLSTATE 42P05 (`prepared statement already exists`). - Code MUST restrict serverless database connection pool configurations to `max: 1` per micro-VM container to prevent connection exhaustion and out-of-order session contamination across concurrent asynchronous operations. - Services MUST implement explicit deallocation or session cleanups (`DEALLOCATE ALL` or driver connection lifecycle hooks) whenever explicit raw prepared statements or session-level advisory locks are executed within an invocation. - Components NEVER re-instantiate Drizzle ORM client instances inside standard request handler bodies; clients must be lazily initialized as immutable module-scoped singletons with statement preparation explicitly disabled. ## Bad vs Good Implementations ### Postgres.js and Drizzle ORM Configuration for Serverless + PgBouncer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default driver configurations use client-side caching of server-side prepared statements. In serverless functions sharing connection poolers (PgBouncer in transaction mode), the backend Postgres process changes per transaction. Attempting to execute the named statement on a physical connection where it was not declared causes missing statement errors, while hitting a connection where it was declared causes '42P05: prepared statement already exists'. Additionally, `max: 10` exhausts database connection limits when serverless functions scale. ```typescript import { drizzle } from 'drizzle-orm/postgres-js'; import postgres from 'postgres'; import { users } from './schema'; import { eq } from 'drizzle-orm'; // ANTI-PATTERN: Default postgres configuration enables prepared statements. // In warm micro-VMs behind PgBouncer in transaction mode, static statement names // persist on pooled physical connections, causing 42P05 crashes on subsequent calls. const queryClient = postgres(process.env.DATABASE_URL!, { max: 10 // Risk of connection exhaustion across Lambda instances }); const db = drizzle(queryClient); // Bad: Static named prepared statement in serverless scope const findUserPrepared = db .select() .from(users) .where(eq(users.id, 1)) .prepare('find_user_by_id'); export async function handler(event: { userId: number }) { return await findUserPrepared.execute(); } ``` #### Production Standard (Correct) > **Standard**: Setting `prepare: false` instructs the driver to execute queries directly via the simple query protocol or anonymous statements without cataloging them by name on the server. Setting `max: 1` ensures each serverless container limits concurrency to a single connection, eliminating connection pool starvation on warm restarts and preventing connection drift. ```typescript import { drizzle } from 'drizzle-orm/postgres-js'; import postgres from 'postgres'; import { users } from './schema'; import { eq } from 'drizzle-orm'; // PRODUCTION INVARIANT: Disable prepared statements when using transaction poolers. // Restrict max pool size to 1 to safeguard against warm Lambda socket multiplication. const client = postgres(process.env.DATABASE_URL!, { prepare: false, // Critical: bypasses server-side prepared statements entirely max: 1, // Standard for serverless: 1 active connection per container idle_timeout: 20, connect_timeout: 10, }); export const db = drizzle(client); export async function handler(event: { userId: number }) { // Queries run inline without persisting statement state across warm VM invocations return await db .select() .from(users) .where(eq(users.id, event.userId)) .execute(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Drizzle ORM Serverless Prepared Statement & Session State Deallocation Standard

Drizzle ORM Serverless Prepared Statement & Session State Deallocation Standard defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic deallocation of prepared statements and transaction-mode pooling compliance in Drizzle ORM across serverless micro-VM runtimes. Eliminates PostgreSQL 42P05 duplicate statement collisions, session state pollution, and connection starvation on PgBouncer, Neon, and AWS RDS Proxy during warm container reuse. 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: Persisting server-side prepared statement handles across warm serverless micro-VM invocations connected to transaction poolers 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	Persisting server-side prepared statement handles across warm serverless micro-VM invocations connected to transaction poolers	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 set `prepare

Engineers MUST ALWAYS set `prepare: false` in the underlying database driver configuration (e.g., `postgres.js`, `pg`) when operating behind a transaction-mode connection pooler (PgBouncer, Supabase Transaction Pooler, Neon, RDS Proxy).

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.