Neon

Reylo on Neon's serverless Postgres

Neon is Postgres, so everything on the Postgres page holds for it.

DialectPostgres
The type check readsThe direct connection string, through direct_url
Queries run on@neondatabase/serverless, pg or postgres.js, through the pooled connection string
TransactionsOn a Pool's client over a WebSocket, not on neon() over HTTP
BranchesEach has connection strings of its own, to type against its schema
Edge runtimesNeon's driver, on the Next.js edge runtime and in Cloudflare Workers
View the schema behind the examples
create table users (
  id serial primary key,
  name text not null,
  email text
);

Connection strings

Neon gives each branch two connection strings. The pooled one's host ends in -pooler:

.env
# pooled, for your app
DATABASE_URL=postgresql://…@ep-name-pooler.us-east-2.aws.neon.tech/neondb
# direct, for the type check
DATABASE_URL_UNPOOLED=postgresql://…@ep-name.us-east-2.aws.neon.tech/neondb

Point direct_url at the direct one:

.reylo.yaml
direct_url: ${DATABASE_URL_UNPOOLED}
  • Neon's pooler is PgBouncer in transaction mode. Your app's queries can go through it, but the type check can fail there, and migrations refuse it: a run holds a session, which the pooler shares between clients.
  • Without this line, Reylo reads DATABASE_URL and nothing else. DATABASE_URL_UNPOOLED is the name Neon's Vercel integration gives the direct string.
  • The type check takes the string as Neon writes it, sslmode=require and channel_binding=require included (TLS).

Serverless driver

Pass neon() from @neondatabase/serverless, which sends each query over HTTP:

import {  } from "@neondatabase/serverless";
import  from "./get_user.sql";

const  = (..);
const user = await .(, { : 1 });
const user: {
    id: number;
    name: string;
    email: string | null;
} | null
select id, name, email
from users
where id = :id

A Pool or Client from the same package works too, over a WebSocket. Passed a Pool, each query runs on a client the pool checks out for it.

Transactions

Run a transaction on a client checked out of a Pool:

import {  } from "@neondatabase/serverless";
import  from "./create_user.sql";

const  = new ({ : .. });

// both inserts land, or neither
const  = await .();
try {
  await .("begin");
  await .(, { : "Ada" });
  await .(, { : "Grace" });
  await .("commit");
} catch () {
  await .("rollback");
  throw ;
} finally {
  .();
}
insert into users (name)
values (:name)
returning id
  • The transaction() of neon() takes queries built with Neon's own sql tag, so a Reylo query can't join one.
  • Drizzle over Neon's driver has transactions over a Pool, and none over HTTP (Drizzle).

TCP drivers

Over TCP, pass a pg pool or a postgres.js client made with the pooled connection string:

import  from "pg";
import  from "./get_user.sql";

const  = new .({ : .. });
const  = await .(, { : 1 });
import  from "postgres";
import  from "./get_user.sql";

const  = (..);
const  = await .(, { : 1 });

Each runs a transaction its own way: on a client checked out of the pool with pg, and in db.begin() with postgres.js (Drivers).

Branches

Neon's CLI prints a branch's direct connection string:

Terminal
# add --pooled for the pooled one
neon connection-string my-branch

To type against your own branch, set it in .env.local, which Reylo reads before .env:

.env.local
DATABASE_URL_UNPOOLED=postgresql://…@ep-mine.us-east-2.aws.neon.tech/neondb

A branch starts with its parent's schema, so run your migrations on it before the type check reads it.

Pull requests

In CI, create a branch for each pull request with Neon's GitHub Action, migrate it, and type-check against it:

.github/workflows/ci.yml
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      # ...
      - id: branch
        uses: neondatabase/create-branch-action@v6
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          api_key: ${{ secrets.NEON_API_KEY }}
          branch_name: pr-${{ github.event.number }}
      - env:
          DATABASE_URL_UNPOOLED: ${{ steps.branch.outputs.db_url }}
        # your migrations, then the type check and the build
        run: |
          npm run migrate
          npm run typecheck
          npm run build

Delete the branch when the pull request closes:

.github/workflows/cleanup.yml
on:
  pull_request:
    types: [closed]
jobs:
  delete:
    runs-on: ubuntu-latest
    steps:
      - uses: neondatabase/delete-branch-action@v3
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          api_key: ${{ secrets.NEON_API_KEY }}
          branch: pr-${{ github.event.number }}
  • The action's db_url is the branch's direct connection string, and db_url_pooled its pooled one.
  • Neon's Vercel integration can also create a branch for each preview deployment, with its own DATABASE_URL_UNPOOLED. It starts with its parent's schema, so run your migrations on it before the build (A host that builds before it migrates).

Edge runtimes

Neon's driver connects over HTTP and WebSockets, so it runs where TCP doesn't, such as a Cloudflare Worker:

import {  } from "@neondatabase/serverless";
import  from "./get_user.sql";

export default {
  async (: Request, : { : string }) {
    const  = (.);
    return .(await .(, { : 1 }));
  },
};
  • In a Worker, it needs no nodejs_compat flag. Cloudflare D1 covers the Vite plugin that loads .sql files there.
  • On the Next.js edge runtime, use it the same way (The edge runtime).
  • In an edge runtime, connect, use and close a Pool or Client within one request.
Released under the MIT License. Copyright © 2026 Colin McDonnell.

On this page