Claimable Postgres Provision

何时使用

• 需要一个即开即用、无需注册/信用卡的 Postgres，用于本地开发、演示、原型、测试环境。
• Agent 为完成任务需要真实数据库（如「做个带真实数据库的 todo app」）而用户没给连接串时，自动开一个并告知。
• 想要一个可丢弃的 DATABASE_URL 写进项目 .env 快速跑起来。

不该用（负边界）：

• 生产负载：用标准 Neon 开通流程，而非临时 claimable 库。
• 需要长期持久化：临时库 72 小时后过期；要保留必须及时打开 claim_url 认领（claim）。
• 需指定区域 / 分支 / 宽配额：区域固定 us-east-2，未认领库无分支且配额更严（见下表）。
• 强关系建模、检索、优化等本身不属于「开库」——开库后转交对应数据库技能。

核心约束：未认领（UNCLAIMED）数据库 72 小时后过期；认领需在浏览器登录/注册 Neon 账号。库立即可用，认领是可选项。

步骤

判断走哪条路：

• REST API（首选，给 Agent 用）：返回结构化 JSON，除 curl 无运行时依赖，便于解析与错误处理。
• CLI（npx get-db@latest --yes）：一条命令开库并写 .env，Node 环境下最省事。
• SDK（get-db）：在 Node 脚本里编程式开库。
• Vite 插件（vite-plugin-db）：Vite 项目 vite dev 时若缺 DATABASE_URL 自动开库。
• 浏览器：用户无法跑 CLI/API 时，引导其访问 https://pg.new。

API 路径：

1. 确认意图：若请求含糊，确认用户要的是临时、免注册库；若明说「临时/快速」则跳过。
2. 开库：POST https://pg.new/api/v1/database，body {"ref": "agent-skills"}（经本技能开库统一用 agent-skills）。
3. 解析响应：取出 connection_string、claim_url、expires_at。
4. 写 .env：写 DATABASE_URL=<connection_string>；不覆盖已有键，先检查再决定。
5. 可选播种：有 seed SQL 则 psql "$DATABASE_URL" -f seed.sql。
6. 汇报：告知写入位置、所用键、claim_url，并提醒「现在即可用，72 小时内 claim 可永久保留」。
7. 可选：给个 SELECT 1 连通性测试。

CLI 路径：先查目标 .env 是否已有 DATABASE_URL（CLI 发现该键会直接退出不开库）；若已存在，给三选项并确认：① 删除/注释旧行后重跑；② --env 写到别的文件（如 .env.local）；③ --key 换变量名。然后用 @latest --yes 加确认过的选项执行 → 校验写入 → 汇报。

指令

• 始终用 @latest（避免缓存旧版）+ --yes（跳过会卡住 Agent 的交互提示）。
• ref 必填且非空，否则 400 Missing referrer。
• API 返回的 connection_string 是 pooled（连接池） URL。需要直连（如 Prisma 迁移）时，把主机名里的 -pooler 去掉；CLI 会自动同时写 pooled 与 direct 两条。
• 状态查询：GET https://pg.new/api/v1/database/{id}，状态流转 UNCLAIMED → CLAIMING → CLAIMED；认领后 connection_string 返回 null。
• 其他包管理器：yarn dlx / pnpm dlx / bunx get-db@latest / deno run -A get-db@latest。
• 认领：API/SDK 把 claim_url 给用户；CLI 用 npx get-db@latest claim（读 .env 里的 claim_url 并自动开浏览器）。用户不能认领进 Vercel 关联的组织，须另选 Neon org。

示例

REST 开库（解析 JSON 后写 .env）：

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

响应（节选）：

{
  "id": "019beb39-...",
  "status": "UNCLAIMED",
  "connection_string": "postgresql://...",
  "claim_url": "https://pg.new/claim/019beb39-...",
  "expires_at": "2026-01-26T14:19:14.580Z"
}

CLI 一步开库 + 写 env（自定义文件、播种、来源标记）：

npx get-db@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql

CLI 写入 .env 的内容：

DATABASE_URL=postgresql://...              # pooled，应用查询用
DATABASE_URL_DIRECT=postgresql://...       # direct，迁移用（如 Prisma）
PUBLIC_POSTGRES_CLAIM_URL=https://pg.new/claim/...

CLI 常用选项：--yes/-y 跳提示｜--env/-e（默认 ./.env）｜--key/-k（默认 DATABASE_URL）｜--prefix/-p（默认 PUBLIC_）｜--seed/-s SQL 文件｜--logical-replication/-L｜--ref/-r。

SDK（Node 编程式开库）：

import { instantPostgres } from 'get-db';
const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } = await instantPostgres({
  referrer: 'agent-skills',
  seed: { type: 'sql-script', path: './init.sql' },
});
// 返回 pooled / direct 连接串、claimUrl、claimExpiresAt(Date)；referrer 必填

Vite 插件：npm install -D vite-plugin-db，vite dev 时缺 DATABASE_URL 自动开库。

注意事项

• 绝不覆盖已有 env 变量：先检查；冲突时 CLI 用 --env/--key，API 则跳过写入。
• 破坏性播种须先问：seed SQL 含 DROP/TRUNCATE/大量 DELETE 前确认。
• 写凭据进 .env 后，确认其被 .gitignore 覆盖；未覆盖则警告用户，勿擅自改 .gitignore。
• 默认与限额：Provider=AWS、Region=us-east-2（claimable 库不可改）、Postgres 17。未认领配额更严：存储 100 MB / 传输 ~1 GB / 无分支 / 72 小时过期；认领（免费版）后约 512 MB / ~5 GB / 有分支 / 不过期。认领会把限额重置为免费版默认。
• 启用 logical replication 后不可关闭。
• 报错对照：缺 ref → 400 Missing referrer；无效 ID → 400 Database not found；JSON body 非法 → 500 Failed to create the database.。
• 生产工作负载请改用标准 Neon 开通；需长期保留则立刻打开 claim_url 认领。

互见

• requires：（无）—— 仅需 curl 或 Node。
• related：neon-serverless-postgres —— 同属 Neon 生态，从临时库升级到正式 serverless Postgres；postgresql-optimization —— 库开好后的查询/索引优化。
• combines_with：neon-serverless-postgres —— 临时库认领后转入正式管理；ORM/迁移技能（Prisma 等）—— 用 direct 连接串跑迁移。

采编自 sickn33/antigravity-awesome-skills（MIT）。