Bun 1.2 Native SQL Streaming Backpressure & Heap Isolation Protocol

--- description: Bun 1.2 Native SQL Streaming Backpressure & Heap Isolation Protocol - Enforces deterministic memory bounds when streaming high-throughput PostgreSQL datasets over HTTP in Bun 1.2. Prohibits full result-set materialization in the JavaScriptCore heap, mandating direct consumption of native SQL binary cursors via bounded ReadableStream pull controllers. globs: src/**/*.{ts,tsx}, server/**/*.{ts,tsx}, api/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-sql-native-streaming-backpressure" --- # Bun 1.2 Native SQL Streaming Backpressure & Heap Isolation Protocol > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Array Materialization and Free-Running Async Iteration Causing Heap Exhaustion and GC Freezes ## System Constraints You are a Principal Software Architect enforcing Bun 1.2 Native SQL streaming invariants. You must prevent memory exhaustion, unbounded heap allocations, and uncontrolled event-loop starvation by enforcing backpressure-governed stream pipelines from Bun's native SQL client directly to HTTP chunked responses. ## Strict Guidelines - Engineers MUST ALWAYS use native SQL cursor queries (`sql.cursor()`) with explicit batch sizing for datasets exceeding 1,000 records or indeterminate result sets. - Engineers MUST NOT invoke `await sql` without pagination or cursor encapsulation on endpoints returning tabular, audit, or export datasets. - Code MUST construct chunked HTTP transfers using `new ReadableStream({ pull(controller) { ... } })` where each pull cycle drives exactly one cursor fetch. - Engineers MUST NEVER use `for await...of` loops without checking downstream backpressure (`controller.desiredSize > 0`) or without pausing cursor iteration when the network socket buffers are saturated. - Services MUST serialize database records into `Uint8Array` buffers via `TextEncoder` or native binary protocols inside the stream pull loop and enqueue immediately to allow immediate GC of record allocations. - Code MUST handle client disconnects by registering `signal.addEventListener('abort', ...)` to aggressively call `cursor.close()` and release native connection pool allocations. ## Bad vs Good Implementations ### PostgreSQL Large Export Pipeline via Bun 1.2 Native Cursor and ReadableStream #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Awaiting the full query result forces Bun to allocate all JavaScript objects simultaneously on the heap. String concatenation compounds allocation overhead, spiking memory usage and starving the event loop during serialization, leading to fatal OOM aborts under load. ```typescript import { SQL } from "bun"; const sql = new SQL(process.env.DATABASE_URL!); export async function handleExport(req: Request): Promise<Response> { // ANTI-PATTERN: Materializes all rows into the JavaScriptCore heap at once. // A 500k row query will allocate gigabytes of V8/JSC objects, triggering multi-second GC pauses or OOM. const rows = await sql`SELECT id, payload, created_at FROM large_events`; let jsonPayload = "["; for (let i = 0; i < rows.length; i++) { jsonPayload += JSON.stringify(rows[i]) + (i < rows.length - 1 ? "," : ""); } jsonPayload += "]"; return new Response(jsonPayload, { headers: { "Content-Type": "application/json" }, }); } ``` #### Production Standard (Correct) > **Standard**: Binds the native PostgreSQL cursor directly to `ReadableStream.pull()`. Memory remains bounded strictly to `BATCH_SIZE` items at any time. Client backpressure throttles the cursor fetches automatically via the stream controller, and client abort signals release database cursors immediately. ```typescript import { SQL } from "bun"; const sql = new SQL(process.env.DATABASE_URL!); export function handleExport(req: Request): Response { const encoder = new TextEncoder(); const BATCH_SIZE = 1000; // PRODUCTION FIX: Cursor-driven ReadableStream with explicit backpressure let cursor: AsyncIterator<any[]> | null = null; let isFirst = true; const stream = new ReadableStream({ async start() { // Acquire cursor with a fixed batch window from native C++ layer cursor = sql`SELECT id, payload, created_at FROM large_events` .cursor(BATCH_SIZE) [Symbol.asyncIterator](); }, async pull(controller) { if (!cursor) return; const { value: chunk, done } = await cursor.next(); if (done) { controller.enqueue(encoder.encode("]")); controller.close(); return; } let payload = isFirst ? "[" : ""; for (let i = 0; i < chunk.length; i++) { payload += (isFirst && i === 0 ? "" : ",") + JSON.stringify(chunk[i]); } isFirst = false; controller.enqueue(encoder.encode(payload)); }, async cancel() { if (cursor && typeof cursor.return === "function") { await cursor.return(); } }, }); req.signal.addEventListener("abort", () => { void stream.cancel(); }); return new Response(stream, { headers: { "Content-Type": "application/json", "Transfer-Encoding": "chunked", "X-Content-Type-Options": "nosniff", }, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native SQL Streaming Backpressure & Heap Isolation Protocol

Bun 1.2 Native SQL Streaming Backpressure & Heap Isolation Protocol defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic memory bounds when streaming high-throughput PostgreSQL datasets over HTTP in Bun 1.2. Prohibits full result-set materialization in the JavaScriptCore heap, mandating direct consumption of native SQL binary cursors via bounded ReadableStream pull controllers. 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 Array Materialization and Free-Running Async Iteration Causing Heap Exhaustion and GC Freezes 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 Array Materialization and Free-Running Async Iteration Causing Heap Exhaustion and GC Freezes	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 use native SQL cursor queries (`sql.cursor()`) with explicit batch sizing for datasets exceeding 1,000 records or indeterminate result sets.

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.