---
title: "Serverless Driver"
description: "Use @neondatabase/serverless to connect from edge runtimes and serverless functions through PgBeam with HTTP or WebSocket transports."
canonical: "https://pgbeam.com/docs/serverless"
last-updated: "2026-09-14T19:37:21.000Z"
---

# Serverless Driver

> Use @neondatabase/serverless to connect from edge runtimes and serverless functions through PgBeam with HTTP or WebSocket transports.

URL: https://pgbeam.com/docs/serverless

Connect from edge runtimes and serverless functions using the `@neondatabase/serverless` driver. PgBeam supports both the HTTP query endpoint and the WebSocket wire protocol. Your `neon()` / `Pool` call sites and every query stay exactly as they are.

Changing the connection-string host is **not** enough on its own. By default
`@neondatabase/serverless` derives its endpoint by rewriting the host: it
replaces the first label with `api.`, so `abc.proxy.pgbeam.app` would resolve
to `https://api.proxy.pgbeam.app/sql`, dropping the `abc` subdomain PgBeam
needs to route your project. Point the driver at PgBeam once, globally, with
`neonConfig` before any query runs:

These two lines are the only addition. Your query call sites do not change. (On Neon's own `*.neon.tech` hosts the defaults work; PgBeam needs the override because its hostnames are not `*.neon.tech`.)

## Setup

## Install the package

For Node.js environments using WebSocket transport, also install `ws`:

## Point the driver at PgBeam

Set `neonConfig` once, before any query runs (see the warning above for why
this is required). In Node.js, also set the WebSocket constructor.

## HTTP transport: `neon()` tagged template

Best for one-shot queries from edge/serverless functions. Each call is a single
HTTP request. No persistent connection required.

## WebSocket transport: `Pool` / `Client`

Best for interactive transactions or session-level features. Uses the
PostgreSQL wire protocol over WebSocket.

With the driver's default configuration, the WebSocket `Pool` / `Client`
connection **hangs** against PgBeam. PgBeam authenticates with SCRAM, and the
driver's default `pipelineConnect: "password"` optimistically pipelines a
cleartext password before it reads the server's auth challenge, so the SCRAM
handshake never completes. Set `neonConfig.pipelineConnect = false` (already
in the `neon-config.ts` above) so the driver waits for the challenge and
completes SCRAM. The HTTP `neon()` path is unaffected; if you only need
one-shot queries, it works with just `fetchEndpoint` set.

## Run a test query

If this returns results, the serverless driver is connected through PgBeam.

## HTTP vs WebSocket

HTTP (`neon()`)

WebSocket (`Pool` / `Client`)

**Best for**

One-shot queries, edge functions

Transactions, session features

**Connection**

Stateless HTTP request

Persistent WebSocket

**Cold start**

None

WebSocket handshake + TLS

**Transactions**

`sql.transaction([...])`

`BEGIN` / `COMMIT` via client

**Pipelining**

Automatic (batched in one request)

PostgreSQL wire protocol

**Max payload**

\~10 MB response

Unlimited streaming

## Edge runtime compatibility

The serverless driver works in any runtime with `fetch` (for HTTP) or `WebSocket` (for WS):

Runtime

HTTP

WebSocket

Notes

Vercel Edge Functions

Yes

Yes

Built-in WebSocket support

Cloudflare Workers

Yes

Yes

Built-in WebSocket support

Deno Deploy

Yes

Yes

Built-in WebSocket support

Bun

Yes

Yes

Built-in WebSocket support

Node.js

Yes

Yes

Requires `ws` package

## Drizzle ORM integration

Use the serverless driver adapters with Drizzle for type-safe queries:

The same `neonConfig` setup applies. Drizzle wraps the Neon driver, so once the endpoint is pointed at PgBeam, your Drizzle schema and queries are unchanged.

## Transactions

Use `sql.transaction()` to run multiple statements in a single HTTP request:

Use standard `BEGIN` / `COMMIT` with a dedicated client:

## Data type notes

PgBeam matches the `@neondatabase/serverless` type contract over the HTTP endpoint. In particular, `bigint` (`int8`), `numeric`, and `money` are returned as **strings**, not numbers: a JavaScript `Number` cannot represent integers above 2^53 or arbitrary-precision decimals without silent loss. Wrap them with `BigInt(...)` or a decimal library as needed.

`json` / `jsonb` are parsed into objects, and arrays into JS arrays, exactly as the Neon driver does.

## Caching and replicas

SQL annotations work the same with the serverless driver:

See Caching and Read Replicas for details.

## Common issues

Issue

Cause

Fix

Requests hit `api.proxy.pgbeam.app` / 404 / wrong project

`neonConfig.fetchEndpoint` not set; driver rewrote the host to `api.`

Set `neonConfig.fetchEndpoint` so requests target the `/sql` path (see Setup step 2)

`WebSocket is not defined`

Node.js missing WS constructor

Install `ws` and set `neonConfig.webSocketConstructor = ws`

WebSocket `Pool` / `Client` connects then hangs, no error

Default `pipelineConnect: "password"` pipelines a cleartext password, but PgBeam uses SCRAM

Set `neonConfig.pipelineConnect = false`. If you only need one-shot queries, use the HTTP `neon()` path instead

`fetch failed` on HTTP endpoint

Network/firewall blocking HTTPS, or `fetchEndpoint` not pointed at `/sql`

Verify the proxy hostname resolves, port 443 is open, and `fetchEndpoint` is set

Slow cold starts with WebSocket

TLS + WS handshake on each invocation

Use HTTP transport for stateless queries

`connection terminated`

Idle timeout exceeded

Use connection pooling or reconnect on error

## Further reading

Connection Pooling: Pool modes and sizing guidance

Caching: TTL, SWR, cache rules, and SQL annotations

Read Replicas: Replica setup and routing

@neondatabase/serverless on npm: Driver documentation