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.
What a Claimable Database Actually Is
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:
It expires automatically after 72 hours if you never claim it.
It carries no Neon account requirement to create or use during that window.
It converts into a normal, permanent Neon database the moment you claim 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.
Before You Start
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.
This single POST request provisions the instance and returns everything you need in the response. No prior setup, login, or project scaffolding required.
Step 2: Read the Response
Neon returns JSON shaped like this:
json
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.
Step 3: Add connection_string to Your .env File
Paste the returned connection_string directly into DATABASE_URL:
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.
Step 4: Restart Your Dev Server
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.
Pooled vs Direct: The Detail That Actually Matters Here
The connection_string Neon returns is a pooled URL, identifiable by -pooler in the hostname:
txt
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:
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.
Letting the CLI Write the .env File
For a brand-new project, the Neon CLI skips the manual copy-paste entirely:
bash
npx neon-new --yes
This command provisions the database and writes both connection strings plus the claim URL into .env automatically:
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 faster path whenever you're starting fresh and want the fewest manual steps.
Claiming the Database Before It Expires
Unclaimed databases expire after 72 hours by default. To keep one permanently:
Open the claim_url from the original response.
Sign in to Neon, or create an account if you don't have one.
Choose the Neon organization the database should belong to.
Complete the transfer.
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.
What You Get Before Claiming
Feature
Unclaimed
Claiming the database moves these limits onto whatever Neon plan your account uses.
FAQ
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.
Copy-Paste Checklist
Wrapping Up
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.