claimable-postgres

首先：使用父级 neon skill 了解 Neon 概览、开始使用 Neon、Neon 开发最佳实践等内容。

如果尚未安装 neon skill，请从 https://neon.com/docs/ai/skills/neon/SKILL.md 获取，或使用以下命令安装：

npx skills add neondatabase/agent-skills --skill neon

可认领的 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 插件）请参阅下方的选择哪种方法？。

选择哪种方法？

• REST API：返回结构化 JSON。除 curl 外无其他运行时依赖。当 Agent 需要可预测的输出和错误处理时，优先使用此方式。
• CLI（npx neon-new@latest --yes）：通过一条命令创建数据库并写入 .env。如果有 Node.js 且用户希望简单设置，此方式很方便。
• SDK（neon-new/sdk）：用于 Node.js 中的脚本或以编程方式创建数据库。
• Vite 插件（vite-plugin-neon-new）：如果缺少 DATABASE_URL，则在执行 vite dev 时自动创建数据库。用户使用 Vite 项目时可采用此方式。
• 浏览器：用户无法运行 CLI 或 API。请引导他们访问 https://neon.new。

自动创建数据库

如果 Agent 需要数据库来完成任务（例如“帮我构建一个使用真实数据库的待办事项应用”），且用户未提供连接字符串，则通过 API 创建一个，并告知用户。请附上认领 URL，方便用户保留数据库。

Agent 工作流

API 方式

1. **确认意图：**如果请求含糊不清，请确认用户想要一个临时、无需注册的数据库。如果用户明确要求快速或临时数据库，则跳过此步骤。
2. **创建数据库：**向 https://neon.new/api/v1/database 发送 POST 请求，并传入 {"ref": "agent-skills"}。
3. **解析响应：**从 JSON 响应中提取 connection_string、claim_url 和 expires_at。
4. **写入 .env：**将 DATABASE_URL=<connection_string> 写入项目的 .env（或用户偏好的文件和键）。未经确认，不要覆盖现有键。
5. **填充数据（如有需要）：**如果用户提供了种子 SQL 文件，请对新数据库运行该文件：

   psql "$DATABASE_URL" -f seed.sql
   

6. **报告：**涵盖输出检查清单中的每一项。
7. **可选：**提供快速连接测试（例如 SELECT 1）。

CLI 方式

1. **检查 .env：**检查目标 .env 中是否已有 DATABASE_URL（或所选键）。如果存在，请勿运行。可建议移除该键、使用 --env 或 --key，并征得确认（参见运行前检查）。
2. **确认意图：**如果请求含糊不清，请确认用户想要一个临时、无需注册的数据库。如果用户明确要求快速或临时数据库，则跳过此步骤。
3. **收集选项：**除非上下文另有提示，否则使用默认值（例如，用户提到自定义环境文件、种子 SQL 或逻辑复制）。
4. **运行：**使用 @latest --yes 以及已确认的选项执行。始终使用 @latest，以避免使用缓存的过期版本。--yes 会跳过可能导致 Agent 停滞的交互式提示。

   npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
   

5. **验证：**确认连接字符串已写入指定文件。
6. **报告：**涵盖输出检查清单中的每一项。
7. **可选：**提供快速连接测试（例如 SELECT 1）。

输出检查清单

始终报告：

• 连接字符串写入的位置（例如 .env）
• 使用的变量键（DATABASE_URL 或自定义键）
• 认领 URL（来自 .env 或 API 响应）
• 未认领的数据库是临时的（72 小时）：数据库目前可用，在 72 小时内认领即可永久保留

安全与用户体验说明

• 不要覆盖现有环境变量。先检查，再使用 --env 或 --key（CLI），或跳过写入（API），以避免冲突。
• 运行具有破坏性的种子 SQL（DROP、TRUNCATE、批量 DELETE）前，请先征求用户同意。
• 对于生产工作负载，建议使用标准 Neon 配置，而不是临时的可认领数据库。
• 如果用户需要长期持久化，请指导他们立即打开认领 URL。
• 将凭据写入 .env 文件后，请检查该文件是否已被 .gitignore 覆盖。如果没有，请提醒用户。未经确认，不要修改 .gitignore。

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	是	用于标识数据库配置者的跟踪标签。通过此技能配置时，请使用 "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.

CLI

npx neon-new@latest --yes

一步完成数据库配置，并将连接字符串写入 .env。始终使用 @latest 和 --yes（跳过可能导致 Agent 卡住的交互式提示）。

运行前检查

检查目标 .env 中是否已存在 DATABASE_URL（或所选键）。如果找到该键，CLI 将退出，不会配置数据库。

如果该键已存在，请向用户提供以下三个选项：

1. 移除或注释掉现有行，然后重新运行。
2. 使用 --env 写入其他文件（例如 --env .env.local）。
3. 使用 --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://...              # pooled (use for application queries)
DATABASE_URL_DIRECT=postgresql://...       # direct (use for migrations, e.g. 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 项目，如果缺少 DATABASE_URL，vite-plugin-neon-new 会在运行 vite dev 时自动配置数据库。使用 npm install -D vite-plugin-neon-new 安装。配置说明请参阅 Claimable Postgres 文档。

认领

认领是可选的。数据库无需认领即可立即使用。如需认领，用户可在浏览器中打开认领 URL，然后登录或创建 Neon 账户来认领数据库。

• API/SDK： 将创建响应中的 claim_url 提供给用户。
• CLI： npx neon-new@latest claim 会从 .env 读取认领 URL，并自动打开浏览器。

用户无法将数据库认领到与 Vercel 关联的组织；必须选择其他 Neon 组织。

Neon 基础设施即代码（neon.ts）

可认领数据库是专为临时使用而设计的，并通过 neon.new（如上所述）配置，因此不会由 neon.ts 管理。用户将数据库认领到 Neon 账户后，它便成为一个普通的 Neon 项目——此时，Neon 的基础设施即代码文件 neon.ts 就是后续管理它的方式（完整参考请参阅 neon 技能）：声明其分支应具备的服务，为每个分支配置计算资源，并获取类型安全的环境变量。

npm i @neon/config

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true, // Neon Auth, once you outgrow a bare connection string
  dataApi: true, // Data API
  branch: (branch) => (branch.exists ? {} : { ttl: "7d" }), // ephemeral non-default branches
});

neon config apply   # provision the declared services (neon deploy is an alias)

如果项目需要分支、多个服务，或纳入版本控制的持久化基础设施，建议先认领数据库，然后采用 neon.ts，而不是重新配置临时的可认领数据库。

默认值和限制

参数	值
提供商	AWS
区域	us-east-2
Postgres	17

可认领数据库无法更改区域。未认领的数据库配额更严格。认领后，限制会重置为免费计划的默认值。

	未认领	已认领（免费计划）
存储	100 MB	512 MB
传输量	1 GB	~5 GB
分支	否	是
有效期	72 小时	无