关于
通过 Neon 的 Claimable Postgres（pg.new）即时配置临时 PostgreSQL 数据库。无需登录或信用卡。用于快速 Postgres 环境和原型开发的一次性 DATABASE_URL。
name: claimable-postgres description: 通过 Neon 的 Claimable Postgres (pg.new) 即时配置临时 Postgres 数据库。无需登录或信用卡。用于快速 Postgres 环境和原型开发的一次性 DATABASE_URL。 risk: unknown source: community
Claimable Postgres
用于本地开发、演示、原型设计和测试环境的即时 Postgres 数据库。无需账户。数据库在 72 小时后过期，除非认领到 Neon 账户。
快速开始
curl -s -X POST "https://pg.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 插件），参见下方选择哪种方法？。
选择哪种方法？
- REST API：返回结构化 JSON。除
curl外无运行时依赖。当代理需要可预测的输出和错误处理时首选。 - CLI（
npx get-db@latest --yes）：一条命令完成配置并写入.env。当 Node.js 可用且用户想要简单设置时方便。 - SDK（
get-db/sdk）：Node.js 中的脚本或程序化配置。 - Vite 插件（
vite-plugin-db）：如果DATABASE_URL缺失，在vite dev时自动配置。当用户有 Vite 项目时使用。 - 浏览器：用户无法运行 CLI 或 API。引导至 https://pg.new。
REST API
基础 URL： https://pg.new/api/v1
创建数据库
curl -s -X POST "https://pg.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://pg.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://pg.new/api/v1/database/{id}"
返回相同的响应结构。状态转换：UNCLAIMED -> CLAIMING -> CLAIMED。数据库被认领后，connection_string 返回 null。
错误响应
| 条件 | HTTP | 消息 |
|-----------|------|---------|
| 缺少或为空的 ref | 400 | Missing referrer |
| 无效的数据库 ID | 400 | Database not found |
| 无效的 JSON body | 500 | Failed to create the database. |
CLI
npx get-db@latest --yes
一步完成数据库配置并将连接字符串写入 .env。始终使用 @latest 和 --yes（跳过会阻塞代理的交互式提示）。
运行前检查
检查 DATABASE_URL（或选择的键）是否已存在于目标 .env 中。如果找到该键，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 get-db@latest、pnpm dlx get-db@latest、bunx get-db@latest、deno run -A get-db@latest。
输出
CLI 写入目标 .env：
DATABASE_URL=postgresql://... # 池化（用于应用查询）
DATABASE_URL_DIRECT=postgresql://... # 直接（用于迁移，如 Prisma）
PUBLIC_POSTGRES_CLAIM_URL=https://pg.new/claim/...
SDK
用于脚本和程序化配置流程。
import { instantPostgres } from 'get-db';
const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } = await instantPostgres({
referrer: 'agent-skills',
seed: { type: 'sql-script', path: './seed.sql' }
});
