claimable-postgres

FIRST: Use the parent neon skill for a Neon overview, getting started with Neon, Neon development best practices, and more.

If the neon skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:

npx skills add neondatabase/agent-skills --skill neon

Claimable Postgres

Instant Postgres databases for local development, demos, prototyping, and test environments. No account required. Databases expire after 72 hours unless claimed to a Neon account.

Quick Start

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

Parse connection_string and claim_url from the JSON response. Write connection_string to the project's .env as DATABASE_URL.

For other methods (CLI, SDK, Vite plugin), see Which Method? below.

Which Method?

• REST API: Returns structured JSON. No runtime dependency beyond curl. Preferred when the agent needs predictable output and error handling.
• CLI (npx neon-new@latest --yes): Provisions and writes .env in one command. Convenient when Node.js is available and the user wants a simple setup.
• SDK (neon-new/sdk): Scripts or programmatic provisioning in Node.js.
• Vite plugin (vite-plugin-neon-new): Auto-provisions on vite dev if DATABASE_URL is missing. Use when the user has a Vite project.
• Browser: User cannot run CLI or API. Direct to https://neon.new.

Auto-provisioning

If the agent needs a database to fulfill a task (e.g. "build me a todo app with a real database") and the user has not provided a connection string, provision one via the API and inform the user. Include the claim URL so they can keep it.

Agent Workflow

API path

1. Confirm intent: If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
2. Provision: POST to https://neon.new/api/v1/database with {"ref": "agent-skills"}.
3. Parse response: Extract connection_string, claim_url, and expires_at from the JSON response.
4. Write .env: Write DATABASE_URL=<connection_string> to the project's .env (or the user's preferred file and key). Do not overwrite an existing key without confirmation.
5. Seed (if needed): If the user has a seed SQL file, run it against the new database:

   psql "$DATABASE_URL" -f seed.sql
   

6. Report: Cover every item in the Output Checklist.
7. Optional: Offer a quick connection test (e.g. SELECT 1).

CLI path

1. Check .env: Check the target .env for an existing DATABASE_URL (or chosen key). If present, do not run. Offer remove, --env, or --key and get confirmation (see Pre-run Check).
2. Confirm intent: If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
3. Gather options: Use defaults unless context suggests otherwise (e.g., user mentions a custom env file, seed SQL, or logical replication).
4. Run: Execute with @latest --yes plus the confirmed options. Always use @latest to avoid stale cached versions. --yes skips interactive prompts that would stall the agent.

   npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
   

5. Verify: Confirm the connection string was written to the intended file.
6. Report: Cover every item in the Output Checklist.
7. Optional: Offer a quick connection test (e.g. SELECT 1).

Output Checklist

Always report:

• Where the connection string was written (e.g. .env)
• Which variable key was used (DATABASE_URL or custom key)
• The claim URL (from .env or API response)
• That unclaimed databases are temporary (72 hours): the database works now, and claiming within 72 hours keeps it permanently

Safety and UX Notes

• Do not overwrite existing env vars. Check first, then use --env or --key (CLI) or skip writing (API) to avoid conflicts.
• Ask before running destructive seed SQL (DROP, TRUNCATE, mass DELETE).
• For production workloads, recommend standard Neon provisioning instead of temporary claimable databases.
• If users need long-term persistence, instruct them to open the claim URL right away.
• After writing credentials to an .env file, check that it's covered by .gitignore. If not, warn the user. Do not modify .gitignore without confirmation.

REST API

Base URL: https://neon.new/api/v1

Create a database

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

Parameter	Required	Description
ref	Yes	Tracking tag that identifies who provisioned the database. Use "agent-skills" when provisioning through this skill.
enable_logical_replication	No	Enable logical replication (default: false, cannot be disabled once enabled)

The connection_string returned by the API is a pooled connection URL. For a direct (non-pooled) connection (e.g. Prisma migrations), remove -pooler from the hostname. The CLI writes both pooled and direct URLs automatically.

Response:

{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://...",
  "claim_url": "https://neon.new/claim/019beb39-...",
  "expires_at": "2026-01-26T14:19:14.580Z",
  "created_at": "2026-01-23T14:19:14.580Z",
  "updated_at": "2026-01-23T14:19:14.580Z"
}

Check status

curl -s "https://neon.new/api/v1/database/{id}"

Returns the same response shape. Status transitions: UNCLAIMED -> CLAIMING -> CLAIMED. After the database is claimed, connection_string returns null.

Error responses

Condition	HTTP	Message
Missing or empty ref	400	Missing referrer
Invalid database ID	400	Database not found
Invalid JSON body	500	Failed to create the database.

CLI

npx neon-new@latest --yes

Provisions a database and writes the connection string to .env in one step. Always use @latest and --yes (skips interactive prompts that would stall the agent).

Pre-run Check

Check if DATABASE_URL (or the chosen key) already exists in the target .env. The CLI exits without provisioning if it finds the key.

If the key exists, offer the user three options:

1. Remove or comment out the existing line, then rerun.
2. Use --env to write to a different file (e.g. --env .env.local).
3. Use --key to write under a different variable name.

Get confirmation before proceeding.

Options

Option	Alias	Description	Default
--yes	-y	Skip prompts, use defaults	false
--env	-e	.env file path	./.env
--key	-k	Connection string env var key	DATABASE_URL
--prefix	-p	Prefix for generated public env vars	PUBLIC_
--seed	-s	Path to seed SQL file	none
--logical-replication	-L	Enable logical replication	false
--ref	-r	Referrer id (use agent-skills when provisioning through this skill)	none

Alternative package managers: yarn dlx neon-new@latest, pnpm dlx neon-new@latest, bunx neon-new@latest, deno run -A neon-new@latest.

Output

The CLI writes to the target .env:

DATABASE_URL=postgresql://...              # pooled (use for application queries)
DATABASE_URL_DIRECT=postgresql://...       # direct (use for migrations, e.g. Prisma)
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...

SDK

Use for scripts and programmatic provisioning flows.

import { instantPostgres } from "neon-new";

const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } =
  await instantPostgres({
    referrer: "agent-skills",
    seed: { type: "sql-script", path: "./init.sql" },
  });

Returns databaseUrl (pooled), databaseUrlDirect (direct, for migrations), claimUrl, and claimExpiresAt (Date object). The referrer parameter is required.

Vite Plugin

For Vite projects, vite-plugin-neon-new auto-provisions a database on vite dev if DATABASE_URL is missing. Install with npm install -D vite-plugin-neon-new. See the Claimable Postgres docs for configuration.

Claiming

Claiming is optional. The database works immediately without it. To optionally claim, the user opens the claim URL in a browser, where they sign in or create a Neon account to claim the database.

• API/SDK: Give the user the claim_url from the create response.
• CLI: npx neon-new@latest claim reads the claim URL from .env and opens the browser automatically.

Users cannot claim into Vercel-linked orgs; they must choose another Neon org.

Neon Infrastructure as Code (neon.ts)

Claimable databases are deliberately throwaway and provisioned through neon.new (above), so they aren't managed by neon.ts. Once a user claims a database into a Neon account it becomes a normal Neon project — at which point neon.ts, Neon's infrastructure-as-code file, is how you manage it going forward (see the neon skill for the full reference): declare the services its branches should have, program per-branch compute, and get type-safe env vars.

npm i @neon/config

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true, // Neon Auth, once you outgrow a bare connection string
  dataApi: true, // Data API
  branch: (branch) => (branch.exists ? {} : { ttl: "7d" }), // ephemeral non-default branches
});

neon config apply   # provision the declared services (neon deploy is an alias)

If a project needs branching, multiple services, or durable infrastructure tracked in version control, recommend claiming first and then adopting neon.ts — rather than re-provisioning throwaway claimable databases.

Defaults and Limits

Parameter	Value
Provider	AWS
Region	us-east-2
Postgres	17

Region cannot be changed for claimable databases. Unclaimed databases have stricter quotas. Claiming resets limits to free plan defaults.

	Unclaimed	Claimed (Free plan)
Storage	100 MB	512 MB
Transfer	1 GB	~5 GB
Branches	No	Yes
Expiration	72 hours	None