Get a Postgres 17 DB via neon.new with one curl — pooled vs direct URLs, claim link, and no account needed.
Join developers getting comprehensive guides, code examples, optimization tips, and time-saving prompts to accelerate their development workflow.
No spam. Unsubscribe anytime.
You can get a real, working Postgres 17 database with one curl command, no Neon account and no local install needed. The response gives you a pooled connection string to drop straight into .env, a claim link to keep the database past 72 hours, and an expiration timestamp so you know exactly how long you have. This guide covers the full path from that first request to a claimed, permanent database.
I reach for this constantly when spinning up a new client prototype or testing a migration before committing to infrastructure. Spinning up a throwaway Postgres instance used to mean either installing Postgres locally or signing up for a service before writing a single query. Neon's claimable database skips both steps, and the part worth getting right is the pooled-versus-direct URL distinction, since picking the wrong one is the most common mistake once a migration tool enters the picture.
A claimable database is a temporary Neon Postgres instance created through neon.new. It works immediately, runs on Postgres 17 in AWS us-east-2, and stays free for as long as it's unclaimed.
Three properties define it:
This fits local development, side projects, hackathons, prototypes, demos, and short-lived test environments well. Treat it as disposable until you decide otherwise — claiming it is the deliberate step that turns it into something you'd run a real app against long-term.
You need a terminal, curl, and a .env file (or a place to create one). Most PostgreSQL setups expect a DATABASE_URL variable, so that's the target for what you're about to generate.
curl -X POST https://neon.new/api/v1/database \
-H 'Content-Type: application/json' \
-d '{"ref":"your-app-name"}'
The ref value is just a label for your own reference inside Neon's system — pick something that identifies the project:
curl -X POST https://neon.new/api/v1/database \
-H 'Content-Type: application/json' \
-d '{"ref":"my-nextjs-app"}'
This single POST request provisions the instance and returns everything you need in the response. No prior setup, login, or project scaffolding required.
Neon returns JSON shaped like this:
Three fields matter for everything that follows:
connection_string — the database URL your app will connect with.claim_url — the link that transfers this database into your Neon account before it expires.expires_at — the exact moment the unclaimed database disappears.Save the claim_url somewhere you'll find it later, even if claiming isn't on your mind right now. Once the 72-hour window closes, that link stops working and the database is gone.
connection_string to Your .env FilePaste the returned connection_string directly into DATABASE_URL:
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 a .env file already exists in your project, replace the existing DATABASE_URL line. If it doesn't exist yet, create one with that line as the starting point.
Stop and restart your development server after updating .env. Most frameworks read environment variables once at startup, so a running process keeps using whatever DATABASE_URL it loaded before the change, even after the file on disk is updated.
The connection_string Neon returns is a pooled URL, identifiable by -pooler in the hostname:
ep-example-pooler.c-2.us-east-2.aws.neon.tech
Pooled connections are the right default for application queries, local development, and server runtimes — this is what DATABASE_URL should point to in almost every case.
Some migration tools expect a direct connection instead. To build one, take the same connection string and strip -pooler from the hostname:
ep-example.c-2.us-east-2.aws.neon.tech
A complete setup with both looks like this:
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
DATABASE_URL stays pooled for the app. DATABASE_URL_DIRECT exists specifically for migration tooling that asks for it by name. Add any other secrets your project already needs, like PAYLOAD_SECRET, to the same file.
.env FileFor a brand-new project, the Neon CLI skips the manual copy-paste entirely:
npx neon-new --yes
This command provisions the database and writes both connection strings plus the claim URL into .env automatically:
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 faster path whenever you're starting fresh and want the fewest manual steps.
Unclaimed databases expire after 72 hours by default. To keep one permanently:
claim_url from the original response.Claiming removes the expiration, moves the database into your Neon console, and folds it into your normal account setup. One detail to plan around: after claiming, the API's original connection_string field becomes null, so ongoing connection details from that point forward come from the Neon console rather than the original API response.
| Feature | Unclaimed |
|---|
Claiming the database moves these limits onto whatever Neon plan your account uses.
Do I need a Neon account to create the database? No. Creating a claimable database works without signing up. An account only becomes necessary when you decide to claim it.
Do I need to install Postgres locally?
No. Neon provisions a remote Postgres instance, so DATABASE_URL points at a real database from the first request, with no local install involved.
Is this a real Postgres database? Yes. Claimable databases run on Postgres 17 and behave like any standard Neon instance for the 72 hours before expiration.
Should I use the pooled URL or the direct URL? Default to the pooled URL for application development and server runtimes. Reach for the direct URL only when a specific migration tool requires it.
What happens if I do nothing?
The database expires automatically after 72 hours. Save the claim_url from the original response if there's any chance you'll want to keep the database.
How do I keep the database beyond 72 hours?
Open the claim_url, sign in or create a Neon account, pick an organization, and complete the transfer. That removes the expiration entirely.
A free, claimable Neon Postgres instance gets you a real Postgres 17 database in one command, with no install and no account needed up front. The pooled connection string covers normal app development, a direct URL is one hostname edit away for migration tooling, and the claim_url is your safety net whenever a throwaway database turns out to be worth keeping.
Let me know in the comments if you have questions, and subscribe for more practical development guides.
Thanks, Matija
| Storage | 100 MB |
| Transfer | 1 GB |
| Branches | Not available |
| Expiration | 72 hours |
curl command with your own ref value.connection_string from the response.DATABASE_URL in .env.DATABASE_URL_DIRECT by removing -pooler from the hostname.claim_url somewhere safe.claim_url if you want to keep it past 72 hours.