# Postgres

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

```bash
npx extraorbital add postgres
```

```txt
✓ 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`](/docs/quickstart#how-autopilot-decides) 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

```bash
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](/docs/resources/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](/pricing) 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

```ts title="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`:

```bash title=".env"
# drizzle.config.ts, prisma migrate, etc.
DIRECT_URL=$POSTGRES_URL_NON_POOLING
```

## Next

- [Quickstart](/docs/quickstart) — slugs, idempotency and sharing
- [MongoDB](/docs/resources/mongo) — the document-shaped sibling
- [Pricing](/pricing) — plans, allowances and rates

---

More for agents: [Docs index](https://extraorbital.dev/sitemap.md) · [llms.txt](https://extraorbital.dev/llms.txt) · [agents.md](https://extraorbital.dev/agents.md)