Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

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

  1. sets the command’s SET LOCAL limits and takes the migration lock (pg_try_advisory_xact_lock, polled for up to limits.lockWait);
  2. asserts that the marker is still the one apply read and that no attempt is open;
  3. runs the change, asserting each manual origin and destination check in SQL;
  4. asserts that the catalog digest is the destination snapshot’s;
  5. moves the marker and appends the applied event.

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/pg or viborm/postgres with the Neon PostgreSQL TCP URL. A Neon WebSocket Pool from @neondatabase/serverless can also be passed to viborm/pg as pool, and type-checks with any @types/pg: see Neon WebSocket Pool.

Was this page helpful?