neon-postgres

Neon Serverless Postgres

引導使用者完成任何與 Neon 相關的任務：設定、連線、分支以及進階功能。提供可運作的 Neon 連線、完成的功能設定，或來自官方 Neon 文件的具體答案。

Neon 是一個 serverless Postgres 平台，將運算與儲存分離，以實現自動擴展、分支、即時還原和縮減至零。它與 Postgres 完全相容，並可與任何支援 Postgres 的語言、框架或 ORM 搭配使用。

Neon 文件

Neon 文件是所有 Neon 相關資訊的權威來源。在回覆前，務必對照官方文件驗證所有說法。Neon 的功能和 API 會持續演進，因此建議優先擷取最新文件，而非依賴訓練資料。

以 Markdown 格式擷取文件

任何 Neon 文件頁面都可以透過兩種方式以 markdown 格式取得：

1. 在 URL 後加上 .md（最簡單）：https://neon.com/docs/introduction/branching.md
2. 在標準 URL 上請求 text/markdown：curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching

兩者都會回傳相同的 markdown 內容。請根據您的工具支援情況選擇使用。

尋找正確的頁面

文件索引列出了所有可用頁面及其 URL 和簡短說明：

https://neon.com/docs/llms.txt

常見的文件 URL 已整理在下方的主題連結中。如果您需要的頁面未列於此處，請搜尋文件索引：https://neon.com/docs/llms.txt。請勿猜測 URL。

什麼是 Neon

在提供實作建議之前，請使用此部分進行架構說明和術語解釋（組織、專案、分支、端點）。

連結：https://neon.com/docs/introduction/architecture-overview.md

開始使用

在引導使用者進行首次 Neon 設定時，請使用此部分。

檢查現狀

在開始設定之前，檢查使用者的程式碼庫和環境：

• 現有的資料庫連線程式碼
• 現有的 Neon MCP 伺服器或 Neon CLI 設定
• 是否存在 .env 檔案和 DATABASE_URL 環境變數
• 現有的 ORM（Prisma、Drizzle、TypeORM）設定

使用 Neon CLI 或 MCP 伺服器自動設定

提供檢查現有已連線的 Neon 專案或使用 Neon CLI 或 MCP 伺服器建立新專案的選項。如果尚未設定，請使用 --agent 旗標執行 init。使用 npx -y 跳過套件安裝提示。驗證會自動處理。如果使用者尚未登入，它會開啟瀏覽器進行 OAuth，並等待完成後再繼續。

npx -y neonctl@latest init --agent <agent-name>

支援的 --agent 值：cursor、copilot、claude、claude-desktop、codex、opencode、cline、gemini-cli、goose、zed。

這會安裝 Neon 擴充功能（適用於 Cursor/VS Code）或 MCP 伺服器（適用於其他代理程式）、建立 API 金鑰，並將 neon-postgres 代理技能新增至專案。

如果 init 不適用，則可以非互動方式執行個別步驟：

• 擴充功能： cursor --install-extension databricks.neon-local-connect
• MCP 伺服器： npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>
• 代理技能： npx skills add neondatabase/agent-skills --skill neon-postgres --agent <agent-name> -y

如需完整的 CLI 安裝選項，請參閱 https://neon.com/docs/reference/cli-install.md

設定流程

1. 選擇組織和專案

使用 MCP 伺服器或 CLI 列出組織和專案。讓使用者選擇現有專案或建立新專案。

2. 取得連線字串

使用 MCP 伺服器或 CLI 取得連線字串。將其儲存在 .env 中作為 DATABASE_URL。在修改前先讀取檔案，以避免覆寫現有值。

3. 選擇連線方式與驅動程式

請參閱連線方式指南，根據部署平台選擇正確的驅動程式：https://neon.com/docs/connect/choose-connection.md

4. 使用 Neon Auth 進行使用者驗證（如有需要）

對於 CLI 工具、腳本或沒有使用者帳戶的應用程式，請跳過此步驟。如果應用程式需要驗證：使用 MCP 伺服器的 provision_neon_auth 工具，然後參閱驗證總覽（https://neon.com/docs/auth/overview.md）進行設定。如需驗證與資料庫查詢，請參閱 JavaScript SDK 參考（https://neon.com/docs/reference/javascript-sdk.md）。

5. ORM 設定（選用）

檢查現有的 ORM（Prisma、Drizzle、TypeORM）。如果沒有，詢問使用者是否需要。如需 Drizzle 整合，請參閱 https://neon.com/docs/guides/drizzle.md。

6. Schema 設定

• 檢查現有的遷移檔案或 ORM schema
• 如果沒有：提供建立範例 schema 或共同設計的選項

恢復支援

如果恢復設定，請檢查已設定的項目（MCP 連線、包含 DATABASE_URL 的 .env、相依性、schema），並從下一個未完成的步驟繼續。

安全提醒

提醒使用者使用環境變數儲存憑證，切勿提交連線字串，並使用最小權限的資料庫角色。

連線方式與驅動程式

當需要根據執行時期限制（TCP、HTTP、WebSocket、邊緣、serverless、長時間執行）選擇正確的傳輸層和驅動程式時，請使用此部分。

連結：https://neon.com/docs/connect/choose-connection.md

建議：Drizzle + 適合執行時期環境的驅動程式

務必將 Neon 與 ORM（例如 Drizzle）搭配使用，以簡化 schema 管理和遷移。根據執行時期環境對程式碼的處理方式選擇驅動程式：

• 長時間執行或共用執行時期環境 → node-postgres (pg)。 Neon Functions，以及任何函式執行時期在請求之間共用 / 在流動運算（例如 Vercel 的 Fluid compute）上執行的主機，會讓模組範圍的處理程序在多個請求之間保持存活。在模組範圍內只建立一次 pg 連線池，並在請求之間重複使用。
• 完全隔離的 serverless（Lambda 風格）→ Neon 的 serverless 驅動程式 (@neondatabase/serverless)。 像 Netlify 這類主機會為每個請求啟動全新的隔離實例，因此無法重複使用持續的 TCP 連線池；serverless 驅動程式透過 HTTP 進行查詢，專為此設計。

Neon Functions / Vercel / 流動運算 — Drizzle + node-postgres：

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema";

// 在模組範圍內建立一次；由該實例處理的每個請求重複使用。
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
const db = drizzle({ client: pool, schema });

在 Vercel（Fluid compute）上，也使用 @vercel/functions 的 attachDatabasePool 附加連線池，以便函式執行時期在實例暫停前清空閒置連線：

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { attachDatabasePool } from "@vercel/functions";
import * as schema from "./schema";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
attachDatabasePool(pool); // 讓 Vercel 執行時期管理連線池
const db = drizzle({ client: pool, schema });

Netlify 和其他完全隔離的 serverless — Drizzle + Neon serverless 驅動程式：

import { drizzle } from "drizzle-orm/neon-http";
import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle({ client: sql });

Serverless 驅動程式

使用此部分處理 @neondatabase/serverless 的模式，包括 HTTP 查詢、WebSocket 交易和執行時期特定的最佳化。

連結：https://neon.com/docs/serverless/serverless-driver.md

Neon JS SDK

使用此部分處理結合 Neon Auth 與 Data API 的工作流程，包括 PostgREST 風格的查詢和型別化客戶端設定。

連結：https://neon.com/docs/reference/javascript-sdk.md

開發者工具

使用此部分進行本機開發啟用，包括 npx -y neonctl@latest init --agent <agent-name>、VSCode 擴充功能設定和 Neon MCP 伺服器設定。

工具	URL
CLI Init 指令	https://neon.com/docs/reference/cli-init.md
VSCode 擴充功能	https://neon.com/docs/local/vscode-extension.md
MCP 伺服器	https://neon.com/docs/ai/neon-mcp-server.md
Neon CLI	https://neon.com/docs/reference/neon-cli.md

Neon CLI

使用此部分處理終端機優先的工作流程、腳本和 CI/CD 自動化，搭配 neonctl。

連結：https://neon.com/docs/reference/neon-cli.md

Neon Admin API

Neon Admin API 可用於以程式方式管理 Neon 資源。它在幕後由 Neon CLI 和 MCP 伺服器使用，但也可直接用於更複雜的自動化工作流程，或將 Neon 嵌入其他應用程式時使用。

Neon REST API

使用此部分處理直接的 HTTP 自動化、端點層級控制、API 金鑰驗證、速率限制處理和操作輪詢。

連結：https://neon.com/docs/reference/api-reference.md

Neon TypeScript SDK

使用此部分在 TypeScript 中透過 @neondatabase/api-client 實現型別化的 Neon 資源程式控制。

連結：https://neon.com/docs/reference/typescript-sdk.md

Neon Python SDK

使用此部分在 Python 中使用 neon-api 套件實現 Neon 的程式化管理。

連結：https://neon.com/docs/reference/python-sdk.md

Neon Auth

使用此部分處理受管的使用者驗證設定、UI 元件、驗證方法，以及在 Next.js 和 React 應用程式中整合 Neon Auth 的注意事項。

連結：https://neon.com/docs/auth/overview.md

Neon Auth 也內嵌於 Neon JS SDK 中。根據您的使用案例，您可能希望使用 Neon JS SDK 而非單獨使用 Neon Auth。更多詳細資訊請參閱 https://neon.com/docs/connect/choose-connection.md。

Neon 基礎設施即程式碼 (neon.ts)

neon.ts 是 Neon 的分支設定和基礎設施即程式碼檔案：宣告您的分支擁有哪些服務、取得型別安全的環境變數，以及為每個分支設定運算 — 全部在 TypeScript 中完成（完整參考請參閱 neon 技能）。Postgres 始終存在於每個分支上，因此您永遠不需要宣告資料庫本身；您在此編寫的是 Postgres 周邊的表面 — Neon Auth、Data API 以及每個分支的運算設定（自動擴展和縮減至零）。

使用 @neondatabase/config 新增：

npm i @neondatabase/config

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

export default defineConfig({
  auth: true, // Neon Auth（新增 NEON_AUTH_* 環境變數）
  dataApi: true, // Data API（新增 NEON_DATA_API_URL）；需要 auth: true（或外部 IdP）
  // Postgres 存在於每個分支；為每個分支調整其運算：
  branch: (branch) => {
    if (branch.exists) return {}; // 保留現有分支不變
    if (branch.isDefault) return { protected: true }; // 生產環境保留預設運算
    return {
      ttl: "7d", // 非生產分支自動過期（最長 30 天）
      postgres: {
        computeSettings: {
          autoscalingLimitMinCu: 0.25, // 縮減至零
          autoscalingLimitMaxCu: 1, // 保持開發/預覽環境低成本
          suspendTimeout: "5m",
        },
      },
    };
  },
});

從 CLI 協調宣告 — Neon 相當於 terraform plan / apply 的功能：

neonctl config status   # 顯示分支的即時設定
neonctl config plan     # 試執行 diff，顯示 apply 會變更的內容
neonctl config apply    # 佈建宣告的服務/設定
neonctl deploy          # `neonctl config apply` 的別名

由於 neonctl checkout 在建立分支時套用政策，因此新分支會立即套用這些運算設定（以及 Auth / Data API）。簽出_現有_分支永遠不會協調它 — 請執行 neonctl deploy 以套用變更。

由於 neon.ts 是 TypeScript，無效的組合會編譯失敗並顯示可操作的訊息：Data API 預設使用 Neon Auth 驗證請求，因此 dataApi: true 但沒有 auth: true 是型別錯誤（修正方式 — auth: true，或使用 authProvider: 'external' 搭配 jwksUrl — 會顯示在訊息中）。請參閱 neon 技能的型別安全設定注意事項。

使用 @neondatabase/env 的 parseEnv 讀取結果環境變數，並根據政策進行型別驗證：

import { parseEnv } from "@neondatabase/env/v1";
import config from "./neon";

const env = parseEnv(config);
env.postgres.databaseUrl; // 型別安全；啟用 auth / dataApi 會使 env.auth / env.dataApi 出現

分支

當使用者規劃隔離環境、schema 遷移測試、預覽部署或分支生命週期自動化時，請使用此部分。

重點：

• 分支是即時的、寫時複製的克隆（無需完整資料複製）。
• 每個分支都有自己的運算端點。
• 使用 neonctl CLI 或 MCP 伺服器來建立、檢查和比較分支。

連結：https://neon.com/docs/introduction/branching.md

如需詳細的分支建立工作流程（一般分支 vs 僅 schema 分支、從父分支重設、CLI/MCP 選擇），請使用 neon-postgres-branches 技能（如果可用）

或從以下 URL 擷取完整的分支技能：

https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md

如果尚未安裝此技能，您可以使用以下指令安裝：

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

自動擴展

當使用者需要運算根據工作負載自動擴展，並希望獲得關於 CU 大小和執行時期行為的指導時，請使用此部分。

連結：https://neon.com/docs/introduction/autoscaling.md

縮減至零

當最佳化閒置成本並討論暫停/恢復行為（包括冷啟動的取捨）時，請使用此部分。

重點：

• 閒置的運算會自動暫停（預設 5 分鐘，可設定）（除非停用 — 僅限 Launch 和 Scale 方案）
• 暫停後的第一個查詢通常會有冷啟動懲罰（約數百毫秒）
• 運算暫停時，儲存空間仍保持活躍。

連結：https://neon.com/docs/introduction/scale-to-zero.md

即時還原

當使用者需要時間點還原，或希望無需傳統備份還原工作流程即可還原資料狀態時，請使用此部分。

重點：

• 即時還原的歷史視窗取決於方案限制。
• 使用者可以從歷史時間點建立分支。
• Time Travel 查詢可用於歷史檢查工作流程。

連結：https://neon.com/docs/introduction/branch-restore.md

唯讀副本

針對讀取密集型工作負載，當使用者需要專用的唯讀運算而不複製儲存空間時，請使用此部分。

重點：

• 副本是共用相同儲存空間的唯讀運算端點。
• 建立速度快，且擴展獨立於主要運算。
• 典型使用案例：分析、報表和讀取密集型 API。

連結：https://neon.com/docs/introduction/read-replicas.md

連線池

當使用者處於 serverless 或高並發環境，需要安全、可擴展的 Postgres 連線管理時，請使用此部分。

重點：

• Neon 連線池使用 PgBouncer。
• 在端點主機名稱後加上 -pooler 以使用連線池連線。
• 在具有突發並發的 serverless 執行時期中，連線池尤其重要。

連結：https://neon.com/docs/connect/connection-pooling.md

IP 允許清單

當使用者需要透過受信任的網路、IP 或 CIDR 範圍限制資料庫存取時，請使用此部分。

連結：https://neon.com/docs/introduction/ip-allow.md

邏輯複寫

當整合 CDC 管線、外部 Postgres 同步或基於複寫的資料移動時，請使用此部分。

重點：

• Neon 支援原生邏輯複寫工作流程。
• 適用於與外部 Postgres 系統之間的複寫。

連結：https://neon.com/docs/guides/logical-replication-guide.md