Create a free Neon Postgres (Postgres 17) in one curl command; get a pooled DATABASE_URL and an optional direct URL…
Join developers getting comprehensive guides, code examples, optimization tips, and time-saving prompts to accelerate their development workflow.
No spam. Unsubscribe anytime.
If you want a real Postgres database without installing anything locally, Neon gives you a very fast option:
This guide is written to be extremely easy to follow, even if you have never created a cloud database before.
You are creating a temporary Neon Postgres database through neon.new.
This is called a claimable database because:
Neon says these databases are currently provisioned on:
us-east-217This is a very good fit for:
It is not meant to be your long-term production database unless you claim it and move into a normal Neon setup.
You only need:
curl.env fileIf your app uses PostgreSQL, it likely expects a variable called:
DATABASE_URL=
Run this command:
curl -X POST https://neon.new/api/v1/database \
-H 'Content-Type: application/json' \
-d '{"ref":"your-app-name"}'
Replace your-app-name with something simple that identifies your project.
Examples:
curl -X POST https://neon.new/api/v1/database \
-H 'Content-Type: application/json' \
-d '{"ref":"my-nextjs-app"}'
curl -X POST https://neon.new/api/v1/database \
-H 'Content-Type: application/json' \
-d '{"ref":"portfolio-site"}'
Neon will return JSON that looks like this:
{
"id": "01abc123-def4-5678-9abc-def012345678",
"status": "UNCLAIMED",
"neon_project_id": "cool-breeze-12345678",
"connection_string": "postgresql://neondb_owner:npg_xxxx@ep-cool-breeze-pooler.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require",
"claim_url": "https://neon.new/claim/01abc123-def4-5678-9abc-def012345678",
"expires_at": "2026-02-01T12:00:00.000Z",
"created_at": "2026-01-29T12:00:00.000Z",
"updated_at": "2026-01-29T12:00:00.000Z"
}
You do not need to understand every field.
The 3 fields that matter most are:
connection_stringclaim_urlexpires_atHere is what each one means:
connection_string
This is the main database URL you will paste into your app.claim_url
Open this link later if you want to keep the database longer than 72 hours.expires_at
This is the exact expiration time for the temporary database.connection_string into Your .env FileIn most apps, you should paste the returned connection_string into:
DATABASE_URL=postgresql://...
Example:
DATABASE_URL=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-example-pooler.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
If your project already has a .env file, open it and replace the old DATABASE_URL.
If your project does not have one yet, create a .env file and add:
DATABASE_URL=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-example-pooler.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
If your development server is already running, stop it and start it again.
Why:
.env values at startupThe connection_string Neon returns is a pooled URL.
That is usually the correct one for:
You should generally use this for:
DATABASE_URL=...
A pooled Neon hostname contains:
-pooler
Example:
ep-example-pooler.c-2.us-east-2.aws.neon.tech
Some tools prefer a direct database connection for migrations.
To create a direct URL:
connection_string-poolerPooled hostname:
ep-example-pooler.c-2.us-east-2.aws.neon.tech
Direct hostname:
ep-example.c-2.us-east-2.aws.neon.tech
DATABASE_URL=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-example-pooler.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
DATABASE_URL_DIRECT=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-example.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/01abc123-def4-5678-9abc-def012345678
Use this as a simple rule:
DATABASE_URL = pooled URL for the appDATABASE_URL_DIRECT = direct URL for migrations if your tooling wants itIf you want the safest and simplest setup, use this template:
DATABASE_URL=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-example-pooler.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
DATABASE_URL_DIRECT=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-example.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/01abc123-def4-5678-9abc-def012345678
If your app also requires a secret, keep that in the same file too.
Example:
DATABASE_URL=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-example-pooler.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
DATABASE_URL_DIRECT=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-example.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
PAYLOAD_SECRET=your-existing-secret
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/01abc123-def4-5678-9abc-def012345678
.env File for YouIf you want Neon to handle the env file for you, use the CLI:
npx neon-new --yes
According to the Neon docs, this writes values like these into .env:
DATABASE_URL=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-cool-breeze-a1b2c3d4-pooler.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
DATABASE_URL_DIRECT=postgresql://neondb_owner:npg_xxxxxxxxxxxx@ep-cool-breeze-a1b2c3d4.c-2.us-east-2.aws.neon.tech/neondb?channel_binding=require&sslmode=require
# Claimable DB expires at: Sat, 01 Feb 2026 12:00:00 GMT
# Claim it now to your account using the link below:
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/01abc123-def4-5678-9abc-def012345678
This is the easiest option if:
By default, the database expires after 72 hours.
If you want to keep it:
claim_urlAfter you claim it:
Important detail from Neon:
connection_string becomes nullAccording to the Neon docs, unclaimed databases currently have these limits:
| Feature | Unclaimed |
|---|---|
| Storage | 100 MB |
| Transfer | 1 GB |
| Branches | No |
| Expiration | 72 hours |
If you claim the database, limits move to your Neon plan.
No.
You can create the database immediately without an account.
No.
That is one of the biggest advantages of this workflow.
Yes.
Neon’s docs say claimable databases run on Postgres 17.
Use the pooled URL first unless you know you specifically need a direct connection for migrations or tooling.
The database expires after 72 hours.
Yes, but you need to claim it through the claim_url.
If you want the shortest possible version, do this:
curl -X POST https://neon.new/api/v1/database \
-H 'Content-Type: application/json' \
-d '{"ref":"your-app-name"}'
connection_stringDATABASE_URL=...
DATABASE_URL_DIRECT by removing -pooler from the hostnameclaim_urlIf you want a free Postgres database right now, create one with neon.new, paste the returned connection_string into DATABASE_URL, and claim it later only if you want to keep it beyond 72 hours.
neon.new: https://neon.new/