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://pg.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

Parse

connection_string

claim_url

connection_string

.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 get-db@latest --yes

  ): Provisions and writes

  .env

  in one command. Convenient when Node.js is available and the user wants a simple setup.
• SDK (

  get-db/sdk

  ): Scripts or programmatic provisioning in Node.js.
• Vite plugin (

  vite-plugin-db

  ): 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://pg.new.

REST API

Base URL:

https://pg.new/api/v1

Create a database

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

ref

"agent-skills"

enable_logical_replication

The

connection_string

-pooler

Response:

{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://...",
  "claim_url": "https://pg.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://pg.new/api/v1/database/{id}"

Returns the same response shape. Status transitions:

UNCLAIMED

CLAIMING

CLAIMED

connection_string

null

Error responses

ref

Missing referrer

Database not found

Failed to create the database.

CLI

npx get-db@latest --yes

Provisions a database and writes the connection string to

.env

@latest

--yes

Pre-run Check

Check if

DATABASE_URL

.env

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

--yes

-y

false

--env

-e

./.env

--key

-k

DATABASE_URL

--prefix

-p

PUBLIC_

--seed

-s

--logical-replication

-L

false

--ref

-r

agent-skills

Alternative package managers:

yarn dlx get-db@latest

pnpm dlx get-db@latest

bunx get-db@latest

deno run -A get-db@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://pg.new/claim/...

SDK

Use for scripts and programmatic provisioning flows.

import { instantPostgres } from 'get-db';

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

Returns

databaseUrl

databaseUrlDirect

claimUrl

claimExpiresAt

referrer

Vite Plugin

For Vite projects,

vite-plugin-db

vite dev

DATABASE_URL

npm install -D vite-plugin-db

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://pg.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: 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.
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.
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 get-db@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: 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.
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)

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 get-db@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

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

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.

When to Use

Use this skill when tackling tasks related to its primary domain or functionality as described above.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.