claimable-postgres by neondatabase/agent-skills
npx skills add https://github.com/neondatabase/agent-skills --skill claimable-postgres用于本地开发、演示、原型设计和测试环境的即时 Postgres 数据库。无需账户。除非申领到 Neon 账户,否则数据库将在 72 小时后过期。
curl -s -X POST "https://neon.new/api/v1/database" \
-H "Content-Type: application/json" \
-d '{"ref": "agent-skills"}'
从 JSON 响应中解析 connection_string 和 claim_url。将 connection_string 写入项目的 .env 文件,作为 DATABASE_URL。
关于其他方法(CLI、SDK、Vite 插件),请参阅下面的"选择哪种方法?"。
curl 外,无需运行时依赖。当智能体需要可预测的输出和错误处理时,这是首选。广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
npx neon-new@latest --yes):在一个命令中配置并写入 .env。当 Node.js 可用且用户希望简单设置时,这很方便。neon-new/sdk):用于 Node.js 中的脚本或编程式配置。vite-plugin-neon-new):如果 DATABASE_URL 缺失,在 vite dev 时自动配置。当用户拥有 Vite 项目时使用。基础 URL: https://neon.new/api/v1
curl -s -X POST "https://neon.new/api/v1/database" \
-H "Content-Type: application/json" \
-d '{"ref": "agent-skills"}'
| 参数 | 必需 | 描述 |
|---|---|---|
ref | 是 | 用于标识谁配置了数据库的跟踪标签。通过此技能配置时,请使用 "agent-skills"。 |
enable_logical_replication | 否 | 启用逻辑复制(默认:false,一旦启用无法禁用) |
API 返回的 connection_string 是一个池化连接 URL。对于直接(非池化)连接(例如 Prisma 迁移),请从主机名中移除 -pooler。CLI 会自动写入池化和直接两种 URL。
响应:
{
"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"
}
curl -s "https://neon.new/api/v1/database/{id}"
返回相同的响应结构。状态转换:UNCLAIMED -> CLAIMING -> CLAIMED。数据库被申领后,connection_string 返回 null。
| 条件 | HTTP | 消息 |
|---|---|---|
缺少或空的 ref | 400 | Missing referrer |
| 无效的数据库 ID | 400 | Database not found |
| 无效的 JSON 请求体 | 500 | Failed to create the database. |
npx neon-new@latest --yes
在一个步骤中配置数据库并将连接字符串写入 .env。始终使用 @latest 和 --yes(跳过可能使智能体停滞的交互式提示)。
检查目标 .env 中是否已存在 DATABASE_URL(或选定的键)。如果找到该键,CLI 将退出而不进行配置。
如果键已存在,向用户提供三个选项:
--env 写入到不同的文件(例如 --env .env.local)。--key 写入到不同的变量名下。在继续之前获取确认。
| 选项 | 别名 | 描述 | 默认值 |
|---|---|---|---|
--yes | -y | 跳过提示,使用默认值 | false |
--env | -e | .env 文件路径 | ./.env |
--key | -k | 连接字符串环境变量键 | DATABASE_URL |
--prefix | -p | 生成的公共环境变量的前缀 | PUBLIC_ |
--seed | -s | 种子 SQL 文件的路径 | 无 |
--logical-replication | -L | 启用逻辑复制 | false |
--ref | -r | 推荐者 id(通过此技能配置时使用 agent-skills) | 无 |
其他包管理器:yarn dlx neon-new@latest、pnpm dlx neon-new@latest、bunx neon-new@latest、deno run -A neon-new@latest。
CLI 写入到目标 .env:
DATABASE_URL=postgresql://... # 池化(用于应用程序查询)
DATABASE_URL_DIRECT=postgresql://... # 直接(用于迁移,例如 Prisma)
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...
用于脚本和编程式配置流程。
import { instantPostgres } from 'neon-new';
const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } = await instantPostgres({
referrer: 'agent-skills',
seed: { type: 'sql-script', path: './init.sql' },
});
返回 databaseUrl(池化)、databaseUrlDirect(直接,用于迁移)、claimUrl 和 claimExpiresAt(Date 对象)。referrer 参数是必需的。
对于 Vite 项目,如果 DATABASE_URL 缺失,vite-plugin-neon-new 会在 vite dev 时自动配置数据库。使用 npm install -D vite-plugin-neon-new 安装。有关配置,请参阅 可申领的 Postgres 文档。
确认意图: 如果请求不明确,确认用户是否需要临时的、无需注册的数据库。如果他们明确要求快速或临时的数据库,则跳过此步骤。
配置: 向 https://neon.new/api/v1/database 发送 POST 请求,附带 {"ref": "agent-skills"}。
解析响应: 从 JSON 响应中提取 connection_string、claim_url 和 expires_at。
写入 .env: 将 DATABASE_URL=<connection_string> 写入项目的 .env(或用户首选的文件和键)。未经确认,不要覆盖现有的键。
种子数据(如果需要): 如果用户有种子 SQL 文件,针对新数据库运行它:
psql "$DATABASE_URL" -f seed.sql
报告: 告诉用户连接字符串写在了哪里,使用了哪个键,并分享申领 URL。提醒他们:数据库现在即可使用;在 72 小时内申领以永久保留。
可选: 提供一个快速连接测试(例如 SELECT 1)。
检查 .env: 检查目标 .env 中是否存在现有的 DATABASE_URL(或选定的键)。如果存在,则不运行。提供删除、--env 或 --key 选项并获取确认。
确认意图: 如果请求不明确,确认用户是否需要临时的、无需注册的数据库。如果他们明确要求快速或临时的数据库,则跳过此步骤。
收集选项: 使用默认值,除非上下文另有暗示(例如,用户提到自定义 env 文件、种子 SQL 或逻辑复制)。
运行: 使用 @latest --yes 加上确认的选项执行。始终使用 @latest 以避免过时的缓存版本。--yes 跳过可能使智能体停滞的交互式提示。
npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
验证: 确认连接字符串已写入预期文件。
报告: 告诉用户连接字符串写在了哪里,使用了哪个键,以及申领 URL 在 env 文件中。提醒他们:数据库现在即可使用;在 72 小时内申领以永久保留。
可选: 提供一个快速连接测试(例如 SELECT 1)。
始终报告:
.env)DATABASE_URL 或自定义键).env 或 API 响应)申领是可选的。数据库无需申领即可立即使用。若要可选地申领,用户在浏览器中打开申领 URL,在那里登录或创建 Neon 账户以申领数据库。
claim_url。npx neon-new@latest claim 从 .env 读取申领 URL 并自动打开浏览器。用户无法申领到与 Vercel 关联的组织;他们必须选择另一个 Neon 组织。
| 参数 | 值 |
|---|---|
| 提供商 | AWS |
| 区域 | us-east-2 |
| Postgres | 17 |
可申领数据库的区域无法更改。未申领的数据库有更严格的配额。申领会将限制重置为免费计划的默认值。
| 未申领 | 已申领(免费计划)
---|---|---
存储 | 100 MB | 512 MB
传输 | 1 GB | ~5 GB
分支 | 否 | 是
过期时间 | 72 小时 | 无
如果智能体需要一个数据库来完成某项任务(例如"给我构建一个带有真实数据库的待办事项应用"),而用户没有提供连接字符串,则通过 API 配置一个并通知用户。包含申领 URL,以便他们可以保留它。
--env 或 --key(CLI)或跳过写入(API)以避免冲突。DROP、TRUNCATE、大量 DELETE)之前询问。.gitignore。每周安装量
212
仓库
GitHub 星标
41
首次出现
2026 年 2 月 24 日
安全审计
安装于
codex203
cursor202
gemini-cli200
github-copilot200
amp199
opencode199
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.
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 as DATABASE_URL.
For other methods (CLI, SDK, Vite plugin), see Which Method? below.
curl. Preferred when the agent needs predictable output and error handling.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.neon-new/sdk): Scripts or programmatic provisioning in Node.js.vite-plugin-neon-new): Auto-provisions on vite dev if DATABASE_URL is missing. Use when the user has a Vite project.Base URL: https://neon.new/api/v1
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"
}
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.
| 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. |
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).
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:
--env to write to a different file (e.g. --env .env.local).--key to write under a different variable name.Get confirmation before proceeding.
| Option | Alias | Description | Default |
|---|---|---|---|
--yes | -y | Skip prompts, use defaults | false |
--env | -e | .env file path | ./.env |
--key |
Alternative package managers: yarn dlx neon-new@latest, pnpm dlx neon-new@latest, bunx neon-new@latest, deno run -A neon-new@latest.
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/...
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.
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 for configuration.
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.
If the user has a seed SQL file, run it against the new database:
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
Always report:
.env)DATABASE_URL or custom key).env or API response)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.
claim_url from the create response.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.
| 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
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.
--env or --key (CLI) or skip writing (API) to avoid conflicts.DROP, TRUNCATE, mass DELETE)..gitignore without confirmation.Weekly Installs
212
Repository
GitHub Stars
41
First Seen
Feb 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykFail
Installed on
codex203
cursor202
gemini-cli200
github-copilot200
amp199
opencode199
Azure RBAC 权限管理工具:查找最小角色、创建自定义角色与自动化分配
117,000 周安装
-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 |
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).
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).