---
title: Neon HTTP
description: Serverless PostgreSQL driver for Neon
---

## Installation

```bash
pnpm add @neondatabase/serverless
```

## Configuration

```typescript
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](/docs/extensions/permissions#providers) |

`createClient` refuses any other key with a `ClientInitializationError` that
names it.

### With pgvector

```typescript
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`.

```typescript
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:

```sql
SELECT "user"."id" FROM "billing"."user" AS "user"
```

:::warning
**Migration capability is a subset here.** Neon HTTP cannot pin a session.
`apply` runs on it one request per transactional group (see
[Migrations](#migrations) below); `push`, `down`, `reset`, `baseline`,
`resolve`, `reanchor` and locked `verify` need a session-capable driver. Dry-run
`apply` and `down` are unlocked live reads; they do not require a pinned
session, but do require database connectivity.

For those commands, point a `pg` or postgres.js driver (Neon's WebSocket `Pool`
included) at the **same** `namespace`. This is not a `migrationUrl` option or a
hidden second client — it is two drivers you construct.
:::

Raw SQL is never rewritten and keeps ordinary `search_path` semantics — see
[Namespaces](/docs/drivers/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](/docs/schema/scalars/point).

## Serverless Usage

Neon HTTP is optimized for serverless/edge environments:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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 } });
});
```

:::warning
For Neon HTTP, use batch mode (`$transaction([...])`) for operations that can be planned up front. Nested writes are supported inside a batch, but sibling operations cannot read each other's results.
:::

### 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](/docs/migration#atomicity).

## Capabilities

Dynamic transactions reject; batch mode is fully supported via Neon's `transaction()` function. See the [feature matrix](/docs/drivers#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](/docs/drivers/postgresql/pg#neon-websocket-pool).
