Postgres

A Neon Postgres project of your own. Its own compute, its own branches, its own connection string.

AI/LLM: this page is available in plain markdown at /docs/resources/neon.md

npx extraorbital add postgres

✓ Provisioned neon/default (database neondb, us-east-1)
✓ Wrote 6 variables to .env — POSTGRES_URL, POSTGRES_URL_NON_POOLING, …

postgres, pg and neon all work; the resource is addressed neon/default.

What it writes

Variable	Example
`POSTGRES_URL`	`postgresql://neondb_owner:…@ep-cool-dawn-a1b2-pooler.us-east-1.aws.neon.tech/neondb?sslmode=require`
`POSTGRES_URL_NON_POOLING`	the same, without `-pooler` in the host
`POSTGRES_HOST`	`ep-cool-dawn-a1b2-pooler.us-east-1.aws.neon.tech`
`POSTGRES_USER`	`neondb_owner`
`POSTGRES_PASSWORD`
`POSTGRES_DATABASE`	`neondb`

A whole Postgres project, not a database on somebody else's cluster: its own compute, its own branches, and a connection string nobody else holds.

Use POSTGRES_URL for your app. Use POSTGRES_URL_NON_POOLING for migrations and anything else that needs a session rather than a pooled connection — most migration tools will tell you so by failing in a confusing way if you do not.

Why not `DATABASE_URL`

Because extraorbital provision reads your source for the variable names we publish and offers to fill the ones it finds. DATABASE_URL appears in every project that has ever spoken to a database, including the ones already pointed at their own, so claiming it would turn a helpful guess into a wrong one everywhere at once. These six are the names Vercel's own Neon integration writes.

If two services in the catalog could fill the same variable, the CLI asks which one you meant rather than choosing for you. --non-interactive prints the command that answers instead.

Options

npx extraorbital add postgres [--slug <name>] [--region <region>]

Flag	Default	Description
`--slug`	`default`	A second, fully separate database in the same project
`--region`	`us-east-1`	Where the project lives. A Neon region id like `aws-eu-central-1` also works

Options apply at creation. Re-running add with different options returns the existing database unchanged.

Prototype allowance

One database, and what it uses comes out of the $5.00 allowance your account gets once — the same one the AI Gateway spends from.

This is the one resource where that matters, because it is the only one that both holds your data and bills for holding it. A bucket sitting still costs us nothing. A Postgres project bills compute by the CU-hour and storage by the GB-month from the moment something connects, so a database left running quietly will work through the allowance on its own — a small one at roughly $1.60 a month. When the allowance is gone, nothing else provisions either.

On a paid plan there is no count and no allowance: compute is $0.106 per CU-hour, storage $0.35 per GB-month, restore history $0.20 per GB-month, and the first 500 GB of egress per database per month is free. Those are our supplier's own rates, passed on with nothing added, and the ledger shows what each database actually cost rather than an estimate of it.

Scale-to-zero is on, so an idle database stops accruing compute after five minutes. It is also the reason an idle free database still costs something: storage does not scale to zero.

Use it

db.ts

import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.POSTGRES_URL!);

const [{ now }] = await sql`select now()`;

Anything that speaks Postgres works — pg, Prisma, Drizzle, Kysely. Point your migrations at POSTGRES_URL_NON_POOLING:

.env

# drizzle.config.ts, prisma migrate, etc.
DIRECT_URL=$POSTGRES_URL_NON_POOLING

Quickstart — slugs, idempotency and sharing
MongoDB — the document-shaped sibling
Pricing — plans, allowances and rates

← Previous

MongoDB

S3 storage