前言¶

在 AI 辅助写代码的场景里，数据库相关任务往往落在连接串选错、迁移用 pooled 连接、或把 Neon 分支和通用 Postgres 调优混在一起。Neon 把计算与存储拆开，提供自动扩缩容、分支、scale-to-zero 等能力，和普通自建 Postgres 的操作习惯并不完全一致。下面介绍 Neon 官方维护的 neon-postgres Skill：它把 Lakebase Postgres（Neon 核心数据库）在 Neon 访问路径上的连接、迁移、分支、诊断与搜索等做法写进 Agent 可遵循的指引，减少在对话里重复查文档。

这是什么¶

neon-postgres 是 Neon 在 agent-skills 仓库中提供的 Agent Skill，元数据标明父 Skill 为 neon，来源同上 GitHub 路径。

Skill 的 description 概括其范围：围绕 Neon 上的 Lakebase Postgres，覆盖连接（pooled 与 direct）、 schema 迁移、分支、自动扩缩容、scale-to-zero、即时恢复、只读副本、IP 允许列表、逻辑复制，以及 Lakebase Search；并在出现已有 DATABASE_URL、SQL、schema、inspect 或 search 类工作时启用。新建后端、Auth、文件、Functions 与 LLM 调用应交给父 Skill neon；实时查询、响应式 UI 与实时数据交给 neon-realtime。

资料中说明：Lakebase Postgres 运行在 lakebase 架构上，存储与计算解耦，兼容标准 Postgres，可通过任意支持 Postgres 的语言、框架或 ORM 访问；本 Skill 只覆盖经 Neon 的访问路径，登录与用户会话等见 neon-auth。

核心功能¶

与相关 Skill 的分工¶

官方要求：先用父 Skill neon 了解 Neon 概览、入门与开发最佳实践。若未安装 neon，可从 https://neon.com/docs/ai/skills/neon/SKILL.md 获取，或执行：

neon skills -s neon -y

neon-postgres 专注数据库本体在 Neon 上的用法；分支创建的细节流程另有 neon-postgres-branches（可通过 neon skills -s neon-postgres-branches -y 安装）。

接入与连接¶

Setup Flow 分四步，Agent 应按已有上下文避免重复建项目：

1. 选组织与项目：若提示、环境变量、仓库里已有 DATABASE_URL，或 .neon 已指向项目，则直接使用，不要为 schema 工作再列组织或建第二个项目；否则用 CLI（默认）或 MCP 列出并让使用者选择或新建。
2. 拿连接串：已有 DATABASE_URL 则不再通过 CLI/MCP 拉取；否则用 CLI、neon env pull 或 MCP，写入 .env 的 DATABASE_URL，修改前先读文件以免覆盖。
3. 选连接方式与驱动：保留现有 ORM/驱动；无既定选择的 TypeScript schema 工作可参考 Drizzle 文档。按运行环境选驱动（见 Neon「choose connection」文档）；例如 serverless/edge 可用 @neondatabase/serverless（HTTP 单次查询、WebSocket 事务）；Vercel、Cloudflare、Neon Functions 等场景在 Skill 中有对应驱动说明。
4. Schema：以代码管理 schema 与迁移，避免对库做难以追溯的临时 DDL。

Pooled（-pooler）与 direct 的选用（摘自官方表格）：

分支与迁移¶

分支是即时、写时复制（copy-on-write）的克隆，每个分支有独立计算端点；适合隔离环境、迁移在预览数据上验证、预览部署或分支生命周期自动化。更细的分支类型与 CLI/MCP 流程见 neon-postgres-branches。

迁移应在应用到生产前，在生产的分支上、用接近生产的数据做验证；执行迁移必须使用 direct（非 pooled）连接，neon connection-string 默认返回 direct，主机名不应带 -pooler 后缀。

诊断与 Neon 侧性能¶

在手写 catalog 查询前，优先用 Neon 预置的只读诊断：CLI 的 neon inspect db 与 MCP 的 inspect_database 跑同一套检查。症状与检查项对应关系包括：存储占用（table-sizes、index-sizes）、未使用索引与顺序扫描（unused-indexes、seq-scans）、长查询与锁（long-running-queries、locks）、总耗时与调用频次（outliers、calls）、计算缓存与工作集（lfc-hit-rate、working-set）、vacuum 与膨胀（vacuum-stats、bloat）等。若证据指向通用 Postgres 优化（改查询、索引、计划节点），Skill 指向加载 postgres-best-practices 并带上诊断结果继续。

CLI 示例（在已认证且能解析 Neon 上下文时）：

neon inspect db <check>

可用 --project-id、--branch、--database-name 覆盖；仅用 --db-url 时表示直连 Postgres 而非经 Neon API 解析。

搜索与触发词¶

Skill 说明亦适用于 @neondatabase/serverless、@neondatabase/neon-js、neon inspect db，以及 semantic / vector / full-text / BM25 / hybrid search 等 Lakebase Search 相关工作。

安装与启用¶

officialskills.sh 列出的安装方式为：

npx skills add https://github.com/neondatabase/agent-skills --skill neon-postgres

也可向编码助手提供 Skill 目录链接，请求安装：
https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres

父 Skill neon 建议一并安装（见上文 neon skills -s neon -y）。资料未单独区分 Cursor、Codex CLI、Claude Code 的安装差异时，以 npx skills add 与 Neon CLI 的 neon skills 为准。

典型用法（Agent 侧行为）¶

当对话涉及已有 DATABASE_URL、写 SQL、改 schema、inspect 库或做搜索时，Agent 应加载本 Skill 并按 Setup Flow 操作：不重复创建项目；迁移与 pg 管理工具走 direct；Web/serverless 查询走 pooled 或 @neondatabase/serverless。

分支与 CI：用 neon CLI 或 MCP 创建、查看、对比分支；在分支上跑迁移后再合到生产分支。

排障：根据现象选 neon inspect db 的检查名，或 MCP inspect_database；需要分支工作流细节时切换到 neon-postgres-branches。

officialskills.sh 归纳的适用情形包括：为 PR 预览创建隔离分支、坏迁移后按时间点恢复、在 Vercel Edge 经 HTTP 连 Postgres、独立扩展只读副本做分析、用 neonctl 在 CI/CD 中自动化分支生命周期等（与官方 Skill 描述一致，非单独用户案例）。

适用场景与注意¶

适合：已在用或计划用 Neon 的 Postgres 工作负载；Agent 需要稳定遵循「pooled vs direct、分支上测迁移、先用 inspect 再深挖」的团队。

注意：

• 本 Skill 不替代 neon（平台总览与 Auth/Functions 等）、neon-realtime（实时 UI）、neon-auth（登录与会话）。
• 勿对生产直接跑未在分支验证过的 schema 变更。
• 诊断截断时可提高 MCP inspect_database 的 limit（仅当结果提示被截断时）。

Serverless Postgres 与 AI 应用常一起出现；Neon 以官方 Skill 把数据库厂商的最佳实践放进 Agent Skills 生态，neon-postgres 是其中面向 Lakebase Postgres 在 Neon 路径上的专门条目。

结尾¶

neon-postgres 把连接、迁移、分支、平台诊断与搜索相关指引收敛成 Agent 可执行的流程，并与父 Skill、分支子 Skill、通用 Postgres 最佳实践 Skill 划清边界。官方 Skill 目录：

https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres