neon-serverless

library0.5.3jsnpmunverified

@neondatabase/serverless is a PostgreSQL driver optimized for serverless and edge environments (e.g., Vercel Edge, Cloudflare Workers) from Neon.tech. At version 0.5.3 (beta), it offers two APIs: a simple `neon` function for one-shot queries over HTTPS fetch, and Pool/Client for sessions/transactions via WebSockets. It is a drop-in replacement for the popular `pg` package (node-postgres) with message pipelining for low latency. It ships TypeScript types and is ESM-only. Key differentiators: works in edge runtimes without Node.js TCP, supports SQL template tag injection safety, and integrates tightly with Neon's serverless Postgres offering.

database

npm install neon-serverless

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEON-SERVERLESS

neon-serverless

databasejavascriptv0.5.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

neon

✓ import { neon } from '@neondatabase/serverless'

✗ import neon from '@neondatabase/serverless'

Default export is not available; must use named import. ESM-only, no CJS require().

Pool

✓ import { Pool } from '@neondatabase/serverless'

✗ const { Pool } = require('@neondatabase/serverless')

CommonJS require is not supported since v0.x ESM-only. Pool uses WebSockets, requires a WebSocket constructor in Node.js.

Client

✓ import { Client } from '@neondatabase/serverless'

✗ import { Client } from 'pg'

Use the provided Client, not the one from 'pg'. Must be created and closed within each request handler in serverless environments.

NeonConfig

✓ import { NeonConfig } from '@neondatabase/serverless'

✗ import { Config } from '@neondatabase/serverless'

Used for advanced configuration like setting custom WebSocket constructor or fetch implementation.

Shows how to set up and use the `neon` function for a simple one-shot query with SQL template tag safety and TypeScript.

import { neon } from '@neondatabase/serverless'; const sql = neon(process.env.DATABASE_URL ?? ''); async function getPost(postId: number) { const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`; return post; } // Example usage const post = await getPost(1); console.log(post);

Debug

Known issues

breakingESM-only: The package does not support CommonJS require(). Using require() will throw a runtime error.

fix

Use dynamic import or switch to ESM in your project (set `"type": "module"` in package.json).

affects: >=0.1.0

breakingPool/Client cannot be reused across requests in serverless environments (e.g., Vercel Edge, Cloudflare Workers). WebSocket connections are request-scoped.

fix

Create, use, and close Pool/Client inside the request handler. Do not store them globally.

affects: >=0.1.0

deprecatedThe `neon` function's `arrayMode` option is deprecated in favor of the `fullResults` option.

fix

Replace `arrayMode: true` with `fullResults: true` in the options object.

affects: >=0.3.0

gotchaUsing `pg` types directly may cause incompatibility; always import types from `@neondatabase/serverless`.

fix

Use import { Pool, Client, neon } from '@neondatabase/serverless' instead of from 'pg'.

affects: >=0.1.0

gotchaThe `neon` function does not support transactions or multiple statements in one call. Use Pool/Client for transactions.

fix

For transactions, use `import { Pool } from '@neondatabase/serverless'` and wrap queries in `BEGIN`/`COMMIT`.

affects: >=0.1.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/@neondatabase/serverless/index.js from /app/index.js not supported.

Package is ESM-only but being imported with require()

fix

Change to dynamic import: `const { neon } = await import('@neondatabase/serverless');` or set `"type": "module"`.

TypeError: WebSocket is not defined

Using Pool/Client in Node.js without providing a WebSocket constructor

fix

Install the `ws` package and set `NeonConfig.webSocketConstructor = WebSocket;` before creating Pool/Client.

Error: Cannot create a Pool outside of a request handler

Pool is created at module scope in a serverless environment

fix

Move the `new Pool()` call inside the request handler and close it before returning.

Upgrade

Version history

0.5.3latest on npm

Audit

Dependencies

wsoptionalOptional peer dependency for WebSocket support in Node.js environments lacking native WebSocket

pgrequiredInherits types and some internals from the `pg` package for compatibility

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/neondatabase/serverless ↗

packageneon-serverless ↗

homepagehttps://neon.tech ↗