Neon
Reylo on Neon's serverless Postgres
Neon is Postgres, so everything on the Postgres page holds for it.
| Dialect | Postgres |
| The type check reads | The direct connection string, through direct_url |
| Queries run on | @neondatabase/serverless, pg or postgres.js, through the pooled connection string |
| Transactions | On a Pool's client over a WebSocket, not on neon() over HTTP |
| Branches | Each has connection strings of its own, to type against its schema |
| Edge runtimes | Neon'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:
# 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/neondbPoint direct_url at the direct one:
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_URLand nothing else.DATABASE_URL_UNPOOLEDis the name Neon's Vercel integration gives the direct string. - The type check takes the string as Neon writes it,
sslmode=requireandchannel_binding=requireincluded (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 });select id, name, email
from users
where id = :idA 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()ofneon()takes queries built with Neon's ownsqltag, 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:
# add --pooled for the pooled one
neon connection-string my-branchTo type against your own branch, set it in .env.local, which Reylo reads before .env:
DATABASE_URL_UNPOOLED=postgresql://…@ep-mine.us-east-2.aws.neon.tech/neondbA 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:
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 buildDelete the branch when the pull request closes:
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_urlis the branch's direct connection string, anddb_url_pooledits 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_compatflag. Cloudflare D1 covers the Vite plugin that loads.sqlfiles there. - On the Next.js edge runtime, use it the same way (The edge runtime).
- In an edge runtime, connect, use and close a
PoolorClientwithin one request.