claimable-postgres_skill

Overview

This skill provisions instant, temporary Postgres databases via Claimable Postgres by Neon (pg.new) with no login, signup, or credit card required. It supports REST API, CLI, SDK, and a Vite plugin so agents can return a working DATABASE_URL for prototyping, demos, or tests. Databases expire after 72 hours unless claimed to a Neon account.

How this skill works

The skill calls the pg.new REST API (or runs the get-db CLI / SDK) with a required referrer tag (use "agent-skills"). The API returns a JSON payload with connection_string, claim_url, and expires_at. The connection string can be written to a .env file (DATABASE_URL) or returned directly to the user. The CLI and SDK also provide direct and pooled URLs, and the CLI can seed databases and write env files automatically.

When to use it

• You need a throwaway Postgres DATABASE_URL immediately for prototyping or CI tests.
• The user requests "quick postgres", "pg.new", or "no signup database".
• A demo or local dev environment needs a disposable DB without account setup.
• Agent must auto-provision a DB when no DATABASE_URL is provided and is required to complete a task.
• You want a short-lived DB for running migrations, seeds, or smoke tests.

Best practices

• Always check the target .env for an existing key before writing; do not overwrite without confirmation.
• Use the REST API for predictable JSON output when the agent must parse results programmatically.
• Use npx get-db@latest --yes to provision and write env files in one step on Node-capable systems.
• Provide the claim_url to the user and remind them to claim within 72 hours for permanent ownership.
• Warn about seed SQL that performs destructive operations and ask for explicit consent before running.

Example use cases

• Agent boots a sandboxed Postgres for a quick demo and writes DATABASE_URL to .env.
• Provision a test database in CI to run migrations and integration tests, then discard it.
• Create a temporary DB for a user building a small feature without requiring account creation.
• Auto-provision a DB when running a Vite dev server if DATABASE_URL is missing.
• Programmatically seed and test database migrations via the SDK in a setup script.