首要事項：請先使用父技能 neon 以取得 Neon 概覽、開始使用 Neon、Neon 開發最佳實務等資訊。
如果尚未安裝 neon 技能，請從 https://neon.com/docs/ai/skills/neon/SKILL.md 取得，或使用以下指令安裝：
npx skills add neondatabase/agent-skills --skill neon
Lakebase Postgres 分支管理
預期成果： 建立一個 Neon 分支——若無法建立，則提供明確、可執行的下一步。選擇正確的分支類型，然後透過 CLI（或當 CLI 無法使用時使用 MCP）執行分支建立。
- 普通分支：用於使用真實資料進行模擬遷移與查詢測試。
- 僅綱要分支（Beta）：用於需要結構但無需複製資料列的敏感資料工作流程。
分支類型決策
請優先使用此決策規則：
- 如果使用者想要測試複雜的遷移、效能或與實際生產環境相似的資料行為，請選擇普通分支。
- 如果使用者需要避免複製敏感資料，請選擇僅綱要分支。
如果請求不明確，請提出一個澄清問題： 「您需要真實的資料進行測試，還是因為資料敏感而只需要綱要結構？」
工具選擇：CLI 或 MCP
支援 Neon CLI 與 Neon MCP 伺服器，但預設使用 CLI。僅在 CLI 在您的環境中無法使用、被封鎖、無法驗證，或使用者明確要求 MCP 時，才使用 MCP。
選擇順序
- 首先檢查 CLI：
- 執行
neon --version確認 CLI 已安裝。 - 執行
neon projects list確認驗證/上下文。
- 執行
- 如果缺少 CLI，透過快速入門指引安裝。
- 如果 CLI 已安裝但未驗證，引導使用者進行
neon auth（或 API 金鑰驗證），然後繼續。 - 當 CLI 無法使用時——環境中無 CLI 存取權限、執行被封鎖、或無法驗證——或使用者明確要求 MCP 時，切換至 MCP。確認 Neon MCP 工具可用且已驗證（例如列出專案可以正常運作），然後遵循下方的 MCP 分支流程。
- 如果兩種路徑都失敗，請使用 Neon REST API：
MCP 分支流程
- 根據資料敏感性和遷移測試目標選擇普通分支或僅綱要分支。
- 使用分支工具（例如
create_branch）建立分支。 - 使用讀取工具（例如
describe_branch）進行驗證。 - 對於遷移工作流程，建議在套用到主分支之前先使用基於分支的遷移流程。
建立普通分支（真實資料遷移測試的首選）
當使用者需要真實的測試條件時使用此選項。 真實的生產環境資料可以揭露種子資料或資料遷移腳本可能遺漏的邊界情況，有助於在正式上線前發現遷移問題。
連結：https://neon.com/docs/introduction/branching.md
步驟
-
先確定工具路徑（請參閱選擇順序）：使用
neon --version驗證 CLI，僅在 CLI 無法使用時才降級至 MCP。 -
確保已設定專案上下文（
neon set-context --project-id <your-project-id>）或在指令中包含--project-id。 -
建立分支：
neon branches create \ --name <branch-name> \ --parent <parent-branch-id-or-name> \ --expires-at 2026-12-15T18:02:16Z -
選擇性地取得新分支的連線字串：
neon connection-string <branch-name>
建立僅綱要分支（Beta，敏感資料）
當使用者必須避免將生產資料列複製到測試分支時使用此選項。
連結：https://neon.com/docs/guides/branching-schema-only.md
步驟
-
先確定工具路徑（請參閱選擇順序）：使用
neon --version驗證 CLI，僅在 CLI 無法使用時才降級至 MCP。 -
建立僅綱要分支：
neon branches create \ --name <schema-only-branch-name> \ --parent <parent-branch-id-or-name> \ --schema-only \ --expires-at 2026-12-15T18:02:16Z如果存在多個專案，請包含
--project-id：neon branches create \ --name <schema-only-branch-name> \ --parent <parent-branch-id-or-name> \ --schema-only \ --project-id <your-project-id> \ --expires-at 2026-12-15T18:02:16Z
Beta 支援指引（強制）
僅綱要分支處於 Beta 階段。如果使用者回報異常行為、錯誤或缺少功能：
- 請他們在 Neon 主控台中分享意見回饋：
- 建議在 Neon Discord 中開啟支援對話：
從父分支重置
當子分支已偏離，且使用者希望從父分支的最新綱要和資料進行乾淨刷新時使用此選項。
連結：https://neon.com/docs/guides/reset-from-parent.md
功能說明
- 完全將子分支的綱要和資料取代為父分支的最新狀態。
- 不會合併；子分支上的本機變更將會遺失。
- 保留相同的連線詳細資料，但重置期間活躍連線會短暫中斷。
何時建議使用
- 開發或暫存分支與正式環境差距過大。
- 使用者希望從與父分支對齊的乾淨狀態開始新功能。
- 團隊希望從正式環境刷新暫存分支，以獲得一致的測試基準。
硬性限制與阻礙
- 只能重置子分支（根分支和僅綱要根分支無法從父分支重置）。
- 如果目標分支有子分支，則無法進行重置，直到這些子分支被移除。
- 父分支從快照還原後，在最多 24 小時內可能無法使用從父分支重置的功能。
- 從父分支重置始終使用目前的父分支狀態；如需時間點還原，請使用即時還原 (Instant restore)。
CLI 使用方式
neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name>
如果尚未設定專案上下文，請包含專案 ID：
neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>
--preserve-under-name 會將重置前的狀態保留為備份分支以供回滾，但會增加一個需要稍後清理的額外分支。
可以選擇設定上下文以避免重複 --project-id：
neon set-context --project-id <project-id>
主控台與 API 使用方式
- 主控台： 開啟目標子分支，然後從動作選單中選擇從父分支重置。
- API： 使用分支的還原端點，並將
source_branch_id設定為父分支 ID。
注意事項與提醒
- 僅綱要分支僅用於結構複製和敏感/合規資料控制。
- 僅綱要分支是獨立的根分支（沒有父分支且無共享歷史記錄），因此不適用從父分支重置。
- 對於依賴真實資料行形狀、資料量和邊界情況的遷移測試，建議使用普通分支。
- 根分支配額和每個分支的儲存限制可能會限制使用者可以建立的僅綱要分支數量。
- 如果使用者不確定，預設建議為：
- 普通分支用於遷移驗證。
- 僅綱要分支用於合規和隱私限制。
實用工作流程模式
如果使用者要求流程建議（不僅僅是單一指令），請建議以下模式：
- 每個 PR 一個分支： 在 PR 開啟時建立分支，合併/關閉時刪除，保持遷移測試隔離。
- 每次測試執行一個分支： 在管線開始時建立分支，執行遷移/測試，結束時刪除以實現確定性 CI。
- 每位開發者一個分支： 隔離的開發環境，具有貼近生產環境的形狀；避免團隊在共享測試資料上的衝突。
- PII 感知分支： 如果正式環境包含敏感資料，則從匿名化分支衍生開發/PR 分支，或使用僅綱要分支。
- 臨時生命週期衛生： 設定分支到期日並自動清理，以避免舊分支累積不必要的儲存/歷史成本。
建立後環境更新提示
分支建立後，詢問使用者是否要更新本機環境憑證，使其指向新的分支。
- 詢問：「您要我將您的
.env的DATABASE_URL更新為這個新分支的連線字串嗎？」 - 如果同意，將新的分支連線字串寫入請求的環境檔案/金鑰。
- 如果不同意，保持憑證不變，並提供連線字串供手動使用。
- 未經明確確認，絕不覆寫現有的環境金鑰。
Neon 基礎設施即程式碼 (neon.ts)
除了命令式地建立分支（上述的 CLI / MCP / API）之外，您還可以以宣告式方式在 neon.ts 中定義新分支應接收的配置——這是 Neon 的基礎設施即程式碼檔案（完整參考請參閱 neon 技能）。branch 屬性是根據被評估的分支回傳其設定的函式，因此從專案產生的每個分支都能獲得一致的生命週期和計算配置，無需為每個分支指定旗標。
npm i @neon/config
// neon.ts
import { defineConfig } from "@neon/config/v1";
export default defineConfig({
branch: (branch) => {
if (branch.exists) return {}; // 永遠不要協調已存在的分支
if (branch.isDefault) return { protected: true };
if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
return {
parent: "main",
ttl: "7d", // 臨時：建立後 7 天自動到期（最長 30 天）
postgres: {
computeSettings: {
autoscalingLimitMinCu: 0.25, // 縮放到零
autoscalingLimitMaxCu: 1, // 保持一次性分支低成本
suspendTimeout: "5m",
},
},
};
}
return {};
},
});
閉包接收目標分支的唯讀描述——name、exists、isDefault、parentId 等——並回傳要套用的調校：parent、ttl（自動到期）、protected 和 postgres.computeSettings。這是上述臨時生命週期衛生和每個 PR / 每次測試模式的宣告式互補：無需記住在每個 neon branches create 上加上 --expires-at，TTL 和計算配置會存在於版本控制中，並套用至每個匹配的分支。
由於 neon checkout 在建立分支時會套用此政策，因此新的 preview/* 或 dev-* 分支在建立時就已設定到期和縮放到零。簽出一個_已存在_的分支不會對其進行協調——請執行 neon deploy（neon config apply 的別名）來將變更套用至已存在的分支。
CI/CD 中的分支
Neon 分支在 CI/CD 中的常見使用案例：
- 每個 PR 的預覽部署： 在 PR 開啟時建立分支，針對它部署預覽，關閉時刪除。每個 PR 獲得一個隔離的資料庫分支。將分支的
DATABASE_URL注入已部署的應用程式取決於託管提供者——請參閱 preview-branches-with-cloudflare、preview-branches-with-vercel 或 preview-branches-with-fly 以取得經過測試的模式。 - CI 中的遷移測試： 在合併前，針對具有生產環境資料的分支執行有風險的綱要變更。
- 綱要差異可視性： 使用 schema-diff GitHub Action 在 PR 上自動留言顯示資料庫層級的差異。
範例
範例 1：使用真實資料進行遷移測試
使用者輸入：「我需要針對生產環境資料測試一個有風險的遷移。」
代理程式輸出格式：
- 建議普通分支並解釋原因。
- 分享文件連結：https://neon.com/docs/introduction/branching
- 先檢查工具路徑（CLI 使用
neon --version；僅在 CLI 不可用時使用 MCP）。 - 提供指令：
neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Zneon connection-string migration-test
範例 2：敏感資料開發工作流程
使用者輸入：「由於合規要求，我們無法複製生產資料。」
代理程式輸出格式：
- 建議僅綱要分支並解釋原因。
- 分享文件連結：https://neon.com/docs/guides/branching-schema-only
- 先檢查工具路徑（CLI 使用
neon --version；僅在 CLI 不可用時使用 MCP）。 - 提供指令：
neon branches create --name compliance-dev --parent main --schema-only --project-id <your-project-id> --expires-at 2026-12-15T18:02:16Z
- 提及 Beta 支援路徑：