Agent-skills claimable-postgres

install

source · Clone the upstream repo

git clone https://github.com/neondatabase/agent-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/neondatabase/agent-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/claimable-postgres" ~/.claude/skills/neondatabase-agent-skills-claimable-postgres && rm -rf "$T"

manifest: skills/claimable-postgres/SKILL.md

source content

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

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.

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:

Remove or comment out the existing line, then rerun.
Use
```
--env
```
to write to a different file (e.g.
```
--env .env.local
```
).
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

DATABASE_URL

is missing. Install with

npm install -D vite-plugin-neon-new

. See the Claimable Postgres docs for configuration.

Agent Workflow

API path

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.

Provision: POST to

https://neon.new/api/v1/database

with

{"ref": "agent-skills"}

Parse response: Extract
```
connection_string
```
,
```
claim_url
```
, and
```
expires_at
```
from the JSON response.
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.

Seed (if needed): If the user has a seed SQL file, run it against the new database:

psql "$DATABASE_URL" -f seed.sql

Report: Tell the user where the connection string was written, which key was used, and share the claim URL. Remind them: the database works now; claim within 72 hours to keep it permanently.
Optional: Offer a quick connection test (e.g.
```
SELECT 1
```
).

CLI path

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.
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.
Gather options: Use defaults unless context suggests otherwise (e.g., user mentions a custom env file, seed SQL, or logical replication).

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

Verify: Confirm the connection string was written to the intended file.
Report: Tell the user where the connection string was written, which key was used, and that a claim URL is in the env file. Remind them: the database works now; claim within 72 hours to keep it permanently.
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)

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.

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

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.

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.