前言¶

在 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