用途
Claimable Postgres 用于快速开通即时的临时 Postgres 数据库，无需登录、注册或信用卡。适用于本地开发、演示、原型设计和测试环境，也可在用户需要快速获得一个 Postgres 环境、一个用于原型或测试的一次性 DATABASE_URL 时使用。数据库默认在 72 小时后过期，除非将其认领到 Neon 账户。
主要能力
- 通过 REST API、CLI、SDK、Vite 插件或浏览器获取临时 Postgres 数据库。
- REST API 返回结构化 JSON，包含 connection_string、claim_url、expires_at 等字段。
- CLI 可一步完成开通并将连接字符串写入 .env。
- SDK 支持脚本或程序化开通。
- Vite 插件在 vite dev 时若缺少 DATABASE_URL 会自动开通。
- 支持可选启用逻辑复制（enable_logical_replication）。
- 支持通过 seed SQL 文件初始化数据。
使用方式
REST API
基础 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 为必填，用于标识开通者；enable_logical_replication 为可选。返回的 connection_string 是池化连接 URL，如需直连（例如 Prisma 迁移），可从主机名中移除 -pooler。
查询状态：
curl -s "https://neon.new/api/v1/database/{id}"
状态流转：UNCLAIMED -> CLAIMING -> CLAIMED。认领后 connection_string 返回 null。
错误响应：缺少或空的 ref 返回 400 Missing referrer；无效数据库 ID 返回 400 Database not found；无效 JSON 体返回 500 Failed to create the database。
CLI
npx neon-new@latest --yes
一步开通数据库并将连接字符串写入 .env。始终使用 @latest 和 --yes。
运行前检查：检查目标 .env 中是否已存在 DATABASE_URL（或所选键）。若存在，CLI 会退出而不开通。此时可提供三个选项：删除或注释掉现有行后重试；使用 --env 写入其他文件；使用 --key 写入其他变量名。需先获得确认。
选项：--yes/-y 跳过提示；--env/-e 指定 .env 路径（默认 ./.env）；--key/-k 指定连接字符串环境变量键（默认 DATABASE_URL）；--prefix/-p 生成公共环境变量前缀（默认 PUBLIC_）；--seed/-s 指定 seed SQL 文件路径；--logical-replication/-L 启用逻辑复制；--ref/-r 指定 referrer id（通过本技能开通时使用 agent-skills）。
其他包管理器：yarn dlx neon-new@latest、pnpm dlx neon-new@latest、bunx neon-new@latest、deno run -A neon-new@latest。
CLI 写入内容示例：
DATABASE_URL=postgresql://... # pooled（用于应用查询） DATABASE_URL_DIRECT=postgresql://... # direct（用于迁移，如 Prisma） PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...
SDK
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 插件
对于 Vite 项目，vite-plugin-neon-new 在 vite dev 时若缺少 DATABASE_URL 会自动开通数据库。安装：npm install -D vite-plugin-neon-new。
浏览器
用户无法运行 CLI 或 API 时，可直接访问 https://neon.new。
适用场景
- 本地开发、演示、原型设计、测试环境。
- 需要快速获得 Postgres 环境或一次性 DATABASE_URL。
- 用户要求“给我一个数据库”时自动开通。
限制
- 默认区域为 AWS us-east-2，Postgres 17，区域不可更改。
- 未认领数据库配额更严格：存储 100 MB、传输 1 GB、无分支、72 小时过期。
- 认领后恢复免费计划默认：存储 512 MB、传输约 5 GB、支持分支、无过期。
- 用户无法认领到与 Vercel 关联的组织，需选择其他 Neon 组织。
- 认领是可选的，数据库无需认领即可立即使用。
- 生产工作负载建议使用标准 Neon 开通方式，而非临时可认领数据库。
- 写入凭据到 .env 后需检查是否被 .gitignore 覆盖，若未覆盖应警告用户，未经确认不要修改 .gitignore。
- 运行破坏性 seed SQL（DROP、TRUNCATE、批量 DELETE）前需询问。
- 不要覆盖现有环境变量。
认领方式
认领是可选的。用户打开 claim URL 在浏览器中登录或创建 Neon 账户即可认领。API/SDK 方式下提供创建响应中的 claim_url；CLI 方式下运行 npx neon-new@latest claim 会从 .env 读取 claim URL 并自动打开浏览器。
Neon 基础设施即代码（neon.ts）
可认领数据库是刻意设计为一次性的，通过 neon.new 开通，因此不由 neon.ts 管理。一旦用户将数据库认领到 Neon 账户，它就成为普通 Neon 项目，此后可用 neon.ts 管理。
npm i @neon/config
// neon.ts import { defineConfig } from "@neon/config/v1";
export default defineConfig({ auth: true, dataApi: true, branch: (branch) => (branch.exists ? {} : { ttl: "7d" }), });
neon config apply # 开通声明的服务（neon deploy 为别名）
若项目需要分支、多服务或版本控制中的持久基础设施，建议先认领再采用 neon.ts，而不是重复开通一次性可认领数据库。