@neondatabase/serverless

@neondatabase/serverless is Neon’s official PostgreSQL driver for JavaScript and TypeScript environments where a raw TCP socket to Postgres isn’t available or isn’t fast enough. It re-exports node-postgres (pg) as a drop-in replacement, so existing Client/Pool code and query libraries built on pg (Kysely, Zapatos, Drizzle, Prisma via @prisma/adapter-neon) keep working, while queries are carried over HTTPS fetch requests or WebSockets rather than a native socket connection.

The driver targets serverless and edge platforms — Cloudflare Workers, Vercel Edge Functions, Deno, and Bun — where TCP is unavailable or connection setup overhead dominates request latency. For one-shot queries it exposes a neon() tagged-template function that pipelines the entire request (connect, authenticate, query) over a single HTTPS round trip; for sessions, interactive transactions, or full node-postgres compatibility it provides Pool and Client classes that tunnel the Postgres wire protocol over WebSockets. SCRAM authentication is reimplemented with SubtleCrypto so the CPU-bound password hashing doesn’t block a serverless function’s limited execution budget.

What You Get

• A neon() tagged-template function for low-latency, single-shot queries pipelined over one HTTPS request
• Pool and Client classes that are drop-in, wire-compatible replacements for node-postgres, tunnelled over WebSockets
• A transaction() helper for issuing multiple non-interactive queries as one atomic HTTPS round trip
• SubtleCrypto-based SCRAM authentication so password hashing doesn’t burn CPU budget in serverless functions
• Configurable connection pipelining (pipelineConnect, pipelineTLS) to cut round trips on supported Neon hosts
• Full TypeScript types re-exported alongside the CommonJS and ESM builds

Common Use Cases

• Querying a Neon database from a Vercel Edge Function or Cloudflare Worker where TCP sockets aren’t available
• Adding Postgres access to a Next.js API route or server action without holding a long-lived pool connection
• Using existing node-postgres-based tooling (Kysely, Zapatos, Prisma via @prisma/adapter-neon) unchanged on serverless infrastructure
• Running interactive transactions or session state (e.g. SET, temp tables) from Deno or Bun via the WebSocket-backed Client
• Migrating an existing pg-based app to serverless deployment via the documented pg → @neondatabase/serverless package alias/override

Under The Hood

Architecture The package is a thin, targeted wrapper around node-postgres rather than a from-scratch driver: src/index.ts re-exports pg’s public surface (types, DatabaseError, escapeIdentifier, etc.) and layers three of its own entry points on top — httpQuery.ts (the neon() tagged-template function and NeonDbError), pool.ts (NeonPool, subclassing pg’s Pool to override query() and route it through neon() when fetch-based querying is enabled and no incompatible listeners are attached), and client.ts (NeonClient, subclassing pg’s Client to add connection pipelining and a SubtleCrypto-based SASL/SCRAM final-message handler). A src/shims/ directory swaps Node built-ins (net, tls, dns, fs, crypto, pg-native) for browser/edge-safe equivalents, letting the same Client/Pool classes run in Node, Deno, Bun, and Cloudflare Workers. The core architectural decision — carrying the Postgres wire protocol over a Socket shim that can back onto either a real TCP-like WebSocket tunnel or a one-shot HTTPS fetch — is what lets both the low-level Pool/Client classes and the HTTP-only neon() function share the same query/type-handling code paths.

Tech Stack Written in TypeScript, built with esbuild via a custom build.sh into parallel CJS (index.js) and ESM (index.mjs) bundles plus matching .d.ts/.d.mts type files, with @microsoft/api-extractor validating the public API surface. It depends directly on pg (re-using its type-overrides and value-preparation internals via non-public imports) and hextreme for fast buffer-to-hex encoding of bytea values, and vendors a subtls TLS implementation for pipelined TLS handshakes against Neon hosts. Test/dev tooling spans an unusually wide matrix: Vitest (Node and edge-runtime environments), Bun, Deno, Playwright (browser tests), Prisma and Drizzle (for adapter compatibility tests), and Wrangler (Cloudflare Workers).

Code Quality The tests/ directory is organized by target runtime (cli, browser, cloudflare, vercel, packages, basic) with package.json scripts wiring a distinct test:* command to each — test:node, test:edge, test:bun, test:deno, test:cloudflare, test:vercel, test:packages, test:browser — reflecting deliberate cross-runtime coverage rather than a single test suite. NeonDbError mirrors pg’s full Postgres error-field set (severity, code, detail, hint, position, etc.) rather than swallowing error detail, and SASL/SCRAM parsing performs explicit format validation (nonce, salt, iteration-count regexes) before proceeding, throwing descriptive errors on malformed server responses. TypeScript strict mode plus Prettier formatting are enforced via npm run format/test:type-shims and a pre-commit hook contributors are asked to install.

API Design The public API is deliberately layered by need: neon() for the common case of stateless HTTP queries with a tagged-template ergonomics (sql`SELECT * FROM posts WHERE id = $\{id\}`, safe from injection by construction), transaction() for grouping several such queries atomically, and Pool/Client for anyone needing full node-postgres session/transaction semantics or compatibility with existing query builders. Because Pool/Client are subclasses of the real pg classes with matching type signatures, adopting the package from pg is largely a drop-in swap (including a documented package.json overrides/alias trick for transitive pg dependents), which keeps the learning curve low for anyone already familiar with node-postgres.