claimable-postgres – Writing & Content skill for AI agents

Claimable Postgres

When to Use

Use this skill when you need provision instant temporary Postgres databases via Claimable Postgres by Neon (neon.new) with no login, signup, or credit card. Supports REST API, CLI, and SDK. Use when users ask for a quick Postgres environment, a throwaway DATABASE_URL for prototyping/tests, or "just give me a DB...

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.

Treat connection and claim URLs as sensitive capabilities: keep them out of public/client environment variables, logs and commits. A name beginning PUBLIC_ does not make a claim link safe to publish. Verify service availability/expiry/quotas from current primary docs and the actual response; do not promise permanent free retention from claiming alone. Inspect seed SQL inertly and verify the new database target before executing.

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 only to an approved ignored private env file without overwriting existing values.

For other methods (CLI, SDK, Vite plugin), see [Which Method?](#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. Use a reviewed version pinned for this task; --yes is appropriate only after all defaults and side effects match authorized scope. Do not silently execute an unreviewed latest package.

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](https://neon.com/docs/reference/claimable-postgres#vite-plugin) for configuration.

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: 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. Pin a reviewed compatible version; inspect the exact package and defaults before using --yes.

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

5. Verify: Confirm the connection string was written to the inte

… (full content is in the download package)