Drizzle ORM Edge Runtime Pooling and Prepared Statement Invariants

--- description: Drizzle ORM Edge Runtime Pooling and Prepared Statement Invariants - Mandates explicit connection pool sizing and prepared statement disabling when configuring Drizzle ORM across ephemeral edge runtimes and transaction poolers (PgBouncer/Supabase/Neon). Prevents connection starvation, 42P05 prepared statement collisions, and micro-VM memory exhaustion under high concurrency. globs: src/**/db/**/*.{ts,tsx}, src/**/database/**/*.{ts,tsx}, src/**/schema/**/*.{ts,tsx}, src/**/*.server.{ts,tsx}, src/app/api/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/drizzle-edge-connection-pooling-prepared-statements" --- # Drizzle ORM Edge Runtime Pooling and Prepared Statement Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Instantiating Per-Request Database Clients and Enabling Prepared Statements Through Transaction-Mode Connection Poolers ## System Constraints You are a Principal Engineer enforcing Drizzle ORM Connection Pooling and Prepared Statement Invariants in Edge Runtimes. Ephemeral micro-VMs (Cloudflare Workers, Vercel Edge, AWS Lambda) must never instantiate unpooled TCP clients per request or rely on prepared statements when connecting to distributed PostgreSQL proxies operating in transaction pooling mode. Enforce singleton client caches, strict connection quotas (max: 1 for serverless TCP), and explicit prepared statement disabling (prepare: false) across all Drizzle driver initializations. ## Strict Guidelines - Engineers MUST ALWAYS disable prepared statements (`prepare: false`) when querying PostgreSQL through transaction-mode connection poolers like PgBouncer, Supabase Pooler (port 6543), or AWS RDS Proxy. - Engineers MUST instantiate database client instances at module scope or attach to `globalThis` to maximize socket reuse across warm invocations in serverless micro-VMs. - Engineers MUST limit client pool sizes to `max: 1` per ephemeral container instance when utilizing persistent TCP drivers like `postgres-js` or `pg`. - Code SHOULD prefer stateless HTTP or WebSocket drivers (such as `@neondatabase/serverless` via HTTP fetch) over stateful TCP pools when operating inside pure edge runtimes with strict socket constraints. - Services MUST configure explicit connection timeouts (`connect_timeout`, `idle_timeout`) to eliminate hung sockets during edge micro-VM freeze/thaw cycles. - Components NEVER initialize `drizzle(...)` or underlying connection drivers inside per-request route handlers, server actions, or middleware functions. ## Bad vs Good Implementations ### Edge Postgres-JS Client Configuration with Drizzle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Instantiating `postgres()` inside a request handler causes connection leakage on every invocation, rapidly starving PostgreSQL's backend pool. Defaulting `prepare: true` triggers PostgreSQL error 42P05 ('prepared statement already exists') when routed through PgBouncer in transaction pooling mode. ```typescript import { drizzle } from 'drizzle-orm/postgres-js'; import postgres from 'postgres'; import * as schema from './schema'; // Anti-pattern: Instantiating client per-request, default prepare: true breaks on PgBouncer export async function POST(req: Request) { const client = postgres(process.env.DATABASE_URL!, { max: 10, // Dangerous: Exceeds edge container quota, quickly starves distributed pool }); const db = drizzle(client, { schema }); const users = await db.query.users.findMany(); return Response.json(users); } ``` #### Production Standard (Correct) > **Standard**: Leverages a module-scoped singleton pattern with `globalThis` caching to reuse sockets across warm invocations. Sets `prepare: false` to eliminate prepared statement collisions through transaction poolers, and enforces `max: 1` to prevent multi-connection micro-VM pool exhaustion. ```typescript import { drizzle } from 'drizzle-orm/postgres-js'; import postgres from 'postgres'; import * as schema from './schema'; declare global { // Invariant: Prevent hot-reload connection leaks across dev-server and warm edge micro-VMs var __postgresClient: postgres.Sql | undefined; } const connectionString = process.env.DATABASE_URL; if (!connectionString) { throw new Error('DATABASE_URL environment variable is required'); } const client = globalThis.__postgresClient ?? postgres(connectionString, { prepare: false, // Invariant: Mandatory for PgBouncer / Supabase transaction poolers max: 1, // Invariant: Limit to single connection per ephemeral container idle_timeout: 20, // Terminate idle connections quickly connect_timeout: 10, // Fail fast if edge cannot reach proxy }); if (process.env.NODE_ENV !== 'production') { globalThis.__postgresClient = client; } export const db = drizzle(client, { schema }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Drizzle ORM Edge Runtime Pooling and Prepared Statement Invariants

Drizzle ORM Edge Runtime Pooling and Prepared Statement Invariants defines an industrial-grade behavioral standard for backend engineering. Mandates explicit connection pool sizing and prepared statement disabling when configuring Drizzle ORM across ephemeral edge runtimes and transaction poolers (PgBouncer/Supabase/Neon). Prevents connection starvation, 42P05 prepared statement collisions, and micro-VM memory exhaustion under high concurrency. 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: Instantiating Per-Request Database Clients and Enabling Prepared Statements Through Transaction-Mode Connection 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	Instantiating Per-Request Database Clients and Enabling Prepared Statements Through Transaction-Mode Connection 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 disable prepared statements (`prepare

Engineers MUST ALWAYS disable prepared statements (`prepare: false`) when querying PostgreSQL through transaction-mode connection poolers like PgBouncer, Supabase Pooler (port 6543), or AWS 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.