How do I provision a Postgres database with Claimable Postgres?

You can provision a database four ways: via REST API (`POST https://pg.new/api/v1/database` with `{"ref": "agent-skills"}`), CLI (`npx get-db@latest --yes`), SDK (`get-db/sdk` for Node.js), or Vite plugin (auto-provisions on `vite dev` if `DATABASE_URL` is missing). The CLI writes the connection string to `.env` in one step.

How long does a Claimable Postgres database last?

Each database expires after 72 hours unless you claim it to a Neon account using the returned claim URL, which makes it permanent.

What connection strings does Claimable Postgres provide?

The API and CLI return both a pooled connection string (`DATABASE_URL`) and a direct connection string (`DATABASE_URL_DIRECT` for tools like Prisma migrations that require direct connections). Strip `-pooler` from the pooled hostname to get the direct connection.

Can I seed the database with initial SQL?

Yes, you can pass a `--seed` option to the CLI with a SQL file path, or use the SDK's `instantPostgres({ seed })` parameter to seed the database programmatically.

Skill

Provision Temporary Postgres Databases

Name: Claimable Postgres
Availability: OnlineOnly
Author: Antigravity

Provisions instant, no-signup Postgres databases via REST API, CLI, or SDK - expires in 72 hours unless claimed to a Neon account.

Get skill

Works with postgresvite

Antigravity

Own this? Claim it

Spark score

out of 100

Updated last month

Version 13.4.0

Add to Favorites

Why it matters

Instantly provision temporary PostgreSQL databases for local development, demos, and prototyping without requiring an account. These databases are ideal for quick testing and development cycles, offering a seamless way to get started with PostgreSQL.

Outcomes

What it gets done

Provision a new PostgreSQL database via API or CLI.

Automatically configure database connection strings in .env files.

Provide a claim URL for permanent database retention.

Support integration with Vite projects for automatic provisioning.

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-claimable-postgres | bash

Overview

Claimable Postgres

Provisions instant, no-signup Postgres databases for local development, demos, prototyping, and testing, via a REST API, CLI (npx get-db@latest), SDK, or Vite plugin. Databases expire after 72 hours unless claimed to a Neon account via the returned claim URL. Use it whenever a project needs a working Postgres database immediately without signup - local dev setup, demos, or test environments. Check for an existing DATABASE_URL in .env first rather than overwriting it, and always claim within 72 hours to keep the database.

What it does

Claimable Postgres provisions instant Postgres databases for local development, demos, prototyping, and test environments with no account required. Each database expires after 72 hours unless claimed to a Neon account via a returned claim URL. It's accessible four ways: a REST API returning structured JSON, a CLI (npx get-db@latest --yes) that provisions and writes .env in one step, an SDK (get-db/sdk) for programmatic Node.js provisioning, and a Vite plugin that auto-provisions on vite dev if DATABASE_URL is missing.

When to use - and when NOT to

Use it whenever a project needs a working Postgres database immediately without signup friction - local dev setup, a demo, a prototype, or a test environment. Choose the REST API when the agent needs predictable JSON output and error handling with no runtime dependency beyond curl; the CLI when Node.js is available and one command should provision plus write .env; the SDK for scripted/programmatic provisioning; the Vite plugin for Vite projects that should auto-provision on dev start; or point a user who can't run CLI/API commands directly to https://pg.new in a browser. Always check whether DATABASE_URL (or the chosen key) already exists in the target .env first - the CLI exits without provisioning if it finds the key, and the agent should offer to remove the existing line, use a different --env file, or a different --key rather than silently overwriting it.

Inputs and outputs

POST https://pg.new/api/v1/database with {"ref": "agent-skills"} (required tracking tag) returns id, status (UNCLAIMED -> CLAIMING -> CLAIMED), connection_string (a pooled URL; strip -pooler from the hostname for a direct connection needed by tools like Prisma migrations), claim_url, and expires_at. GET /database/{id} checks status; after claiming, connection_string returns null. The CLI (npx get-db@latest --yes --ref agent-skills) writes DATABASE_URL (pooled), DATABASE_URL_DIRECT (direct, for migrations), and PUBLIC_POSTGRES_CLAIM_URL to .env, with options for a custom env file (--env), variable name (--key), seed SQL file (--seed), and logical replication (--logical-replication, cannot be disabled once enabled). The SDK's instantPostgres({ referrer, seed }) returns the same values programmatically (databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt).

Integrations

The documented agent workflow is: confirm intent if ambiguous, provision via API or CLI, write the connection string to .env without overwriting an existing key unversioned, optionally seed via psql "$DATABASE_URL" -f seed.sql, then report where the string was written and remind the user to claim within 72 hours to keep the database permanently. Alternative package-manager invocations (yarn dlx, pnpm dlx, bunx, deno run -A) are supported for the CLI path.

Who it's for

Developers and AI agents that need a real, working Postgres database right now for local development, a demo, or a test environment, without going through account signup first - claiming it to a permanent Neon account only if it turns out to be worth keeping.

FAQ

Common questions

Discussion