Neon HTTP
Serverless PostgreSQL driver for Neon
Installation
pnpm add @neondatabase/serverless
Configuration
import { createClient } from "viborm/neon-http";
const client = createClient({
databaseUrl: process.env.DATABASE_URL,
schema,
});
Options
| Option | Type | Description |
|---|---|---|
databaseUrl |
string |
PostgreSQL connection URL |
namespace |
string |
PostgreSQL schema for VibORM-owned objects (default public) |
options.fetchOptions |
RequestInit |
Custom fetch options |
options.authToken |
string or token callback |
JWT authentication passed to the Neon SDK |
pgvector |
boolean |
Enable pgvector support |
postgis |
boolean |
Enable PostGIS support |
sharedRelationBodies |
boolean |
State each relation-filter body a statement repeats once, in a WITH (default true; false keeps the bodies inline) |
relationsPerStatement |
number |
The most relations (FROM items) one statement may reference (PlanetScale Neki: 256); a statement over it is rewritten to fit. See Neki |
createClient refuses any other key with a ClientInitializationError that
names it.
With pgvector
import { createClient } from "viborm/neon-http";
const client = createClient({
databaseUrl: process.env.DATABASE_URL,
pgvector: true,
schema,
});
Namespace
namespace selects the PostgreSQL schema holding this driver’s tables,
junctions, indexes, ORM-managed enums, and migration tracking table. Omitted, it
is public.
import { createClient } from "viborm/neon-http";
const db = createClient({
databaseUrl: process.env.DATABASE_URL,
namespace: "billing",
schema,
});
Qualification happens before execution, so each HTTP request already carries the schema and no setup statement is sent — direct queries and native batches alike:
SELECT "user"."id" FROM "billing"."user" AS "user"
Raw SQL is never rewritten and keeps ordinary search_path semantics — see
Namespaces.
GeoPoint
Neon HTTP can use the PostgreSQL GeoPoint SQL only when the target database has
real PostGIS and the driver is constructed with postgis: true. Hosted
GeoPoint DDL/function/migration convergence was not executed for this release,
so Neon is conditional rather than qualified by the pg/postgres.js evidence.
Use a session-capable pg or postgres.js driver for the required migration
preflight. See GeoPoint.
Serverless Usage
Neon HTTP is optimized for serverless/edge environments:
// Vercel Edge, Cloudflare Workers, etc.
export default async function handler(request: Request) {
const client = createClient({
databaseUrl: process.env.DATABASE_URL,
schema,
});
const users = await client.user.findMany();
return Response.json(users);
}
Transactions & Batching
Neon HTTP does not support traditional dynamic transactions (each HTTP request is a separate connection), but VibORM provides full support for batch mode using Neon’s transaction() function.
Batch Mode (Recommended)
Use the array API for atomic operations - VibORM uses Neon’s transaction() function under the hood:
// Atomic execution using Neon's transaction() function
const [user, post] = await client.$transaction([
client.user.create({ data: { name: "Alice", email: "alice@example.com" } }),
client.post.create({ data: { title: "Hello", authorId: "preset-id" } }),
], { isolationLevel: "Serializable" });
Dynamic Transactions
Dynamic transactions (callback API) are unsupported and reject:
// Throws TransactionError: Neon HTTP does not support callback transactions
await client.$transaction(async (tx) => {
const user = await tx.user.create({ data: { name: "Alice" } });
await tx.post.create({ data: { title: "Hello", authorId: user.id } });
});
Migrations
apply reads the marker, the open attempts and the live schema with ordinary
requests, then sends each transactional group of the change as one request:
a non-interactive transaction that
- sets the command’s
SET LOCALlimits and takes the migration lock (pg_try_advisory_xact_lock, polled for up tolimits.lockWait); - asserts that the marker is still the one
applyread and that no attempt is open; - runs the change, asserting each manual origin and destination check in SQL;
- asserts that the catalog digest is the destination snapshot’s;
- moves the marker and appends the
appliedevent.
A failed assertion raises inside the request and the server rolls all of it
back: the lock taken by another command is V11005, a marker moved meanwhile
V11015, a check or the digest disagreeing V11014, and any other refused
statement V11001. A change that adds an enum value commits in two requests,
as it does on every PostgreSQL driver.
When the reply to that request is lost, apply re-reads the marker while no
command holds the lock. At the target, the outcome is applied. At the
origin, the request did not commit, and the transport error is returned;
running apply again is safe, because the request asserts the marker it read.
When the lock is still held (the request may still be running), apply throws
V11020 and status() settles it later.
Refused before any request carries DDL, with V11021: a stepwise transition
(CONCURRENTLY, or a manual execution: "stepwise" step), including the
CONCURRENTLY states of generate({ lowLock: true }). Refused inside the
request, with V11021 and nothing applied: a destination whose catalog digest
abstains — a partial index, or a default the one-statement digest cannot
reproduce. Apply those over a session-capable driver.
push, down, reset, baseline, resolve, reanchor and locked verify
still refuse (V8002) before provider work: they need a session.
Offline generate and check, estate inspection, and admitted read-only
status, log, and push({ dryRun: true }) remain available.
apply({ dryRun: true }) and down({ dryRun: true }) read the live marker
without a lock, so they need database connectivity. reset({ dryRun: true })
instead previews the estate’s root-to-target path without reading the database,
after target and read-only capability admission. None of these previews grants
permission to execute the corresponding effectful command on Neon HTTP.
For the commands that need a session, use a pg or postgres.js client against
the same database and namespace. See
migration atomicity.
Capabilities
Dynamic transactions reject; batch mode is fully supported via Neon’s transaction() function. See the feature matrix for the full comparison.
Limitations
- Batch operations cannot read each other’s results — use a single nested write for dependent mutations
- HTTP-based: slightly higher latency than traditional connections
- Best suited for serverless environments with simple queries
- For callback transactions on Neon, use
viborm/pgorviborm/postgreswith the Neon PostgreSQL TCP URL. A Neon WebSocketPoolfrom@neondatabase/serverlesscan also be passed toviborm/pgaspool, and type-checks with any@types/pg: see Neon WebSocket Pool.