Neon 無伺服器 PostgreSQL 模式
快速指南: 使用
@neondatabase/serverless進行邊緣/無伺服器資料庫存取。偏好使用neon()HTTP 函數進行單次查詢(更快、無狀態),使用Pool/Client進行互動式交易。使用已池化的連線字串(-pooler尾碼)進行無伺服器工作負載,直連僅用於資料庫遷移。使用寫時複製語意為開發/預覽環境分支出您的資料庫。始終處理從零擴展的冷啟動(200-500毫秒喚醒)。
<critical_requirements>
關鍵:使用此技能前請注意
所有程式碼必須遵循 CLAUDE.md 中的專案慣例(kebab-case、命名匯出、匯入排序、
import type、命名常數)
(您必須在邊緣/無伺服器執行時期使用 neon() HTTP 函數進行單次查詢——對於一次性操作,它比 WebSocket 快 2-3 倍)
(在無伺服器環境中,您必須在同一個請求處理器中關閉 Pool/Client 連線——WebSocket 連線的存活時間不能超過單個請求)
(您必須使用已池化的連線字串(-pooler 尾碼)進行無伺服器工作負載——直連會耗盡有限的連線槽)
(您必須使用適當的連線逾時和重試邏輯來處理從零擴展的喚醒延遲(200-500毫秒))
(您只能對受信任、已知安全的字串(如資料表/欄位名稱)使用 sql.unsafe()——絕不能用於使用者輸入)
</critical_requirements>
自動偵測: Neon, @neondatabase/serverless, neon(), neonConfig, neon serverless driver, neon database, neon branch, neonctl, neon connection pooling, neon scale-to-zero, neon autoscaling, neon postgres, ep-*-pooler
何時使用:
- 從邊緣/無伺服器函數查詢 Postgres(邊緣執行時期、無伺服器平台)
- 為不同的工作負載設定連線字串(已池化 vs 直連)
- 為開發、預覽或 CI 環境建立資料庫分支
- 管理從零擴展的行為和冷啟動最佳化
- 在無伺服器環境中執行交易(HTTP 批次或 WebSocket)
- 透過 Neon API 或 neonctl CLI 進行程式化的分支管理
涵蓋的主要模式:
- 使用 SQL 標記模板和可組合片段的
neon()HTTP 查詢 - 具有正確生命週期管理的
Pool/ClientWebSocket 連線 - 已池化(
-pooler)與直連字串,以及何時使用 - 資料庫分支(開發分支、PR 預覽分支、僅結構分支)
- 從零擴展行為、冷啟動緩解和自動擴展
- 用於非互動式 HTTP 交易的
sql.transaction() - 用於程式化分支管理的 Neon API 和 neonctl CLI
何時不使用:
- 傳統的長生命週期伺服器連線(使用標準的
pg驅動程式搭配 TCP) - 複雜的 ORM 特定模式(使用您 ORM 自己的技能)
- 一般的 PostgreSQL 查詢語法(使用 SQL/Postgres 技能)
詳細資源:
- 有關決策框架和快速查閱表,請參閱 reference.md
驅動程式與查詢:
- examples/core.md -- 驅動程式設定、HTTP 查詢、WebSocket 連線、交易
分支與操作:
- examples/branching.md -- 開發分支、PR 預覽、neonctl CLI、Neon API、CI/CD 工作流程
理念
Neon 將 PostgreSQL 的儲存和運算分離,實現了傳統 Postgres 無法實現的無伺服器功能:從零擴展、即時分支和自動擴展。@neondatabase/serverless 驅動程式用 HTTP 和 WebSocket 取代 TCP,使 Postgres 能夠在缺乏 TCP 支援的邊緣執行時期中存取。
核心原則:
- HTTP 追求速度,WebSocket 追求會話 --
neon()函數使用 HTTP 請求(約 3 次往返)進行單次查詢。當需要會話或互動式交易時,Pool/Client使用 WebSocket(約 8 次往返)。為工作選擇合適的傳輸方式。 - 預設使用連線池 -- 已池化的連線透過 PgBouncer(交易模式)路由,可處理多達 10,000 個並發客戶端。直連受運算大小限制(100-4,000),僅應用於需要會話狀態的遷移或功能。
- 分支成本低廉 -- 寫時複製意味著對 500GB 資料庫進行分支,在資料分歧之前不會分配額外的儲存空間。可自由地將分支用於開發、預覽、測試和 CI。
- 從零擴展是預設行為 -- 運算資源在閒置 5 分鐘後暫停。冷啟動需要 200-500毫秒。透過設定逾時、重試和連線池來為此進行設計。
- 內建 SQL 注入安全性 -- 標記模板函數會自動參數化。從 v1.0 開始,將
neon()作為常規函數呼叫會導致型別錯誤,從而防止意外注入。
何時使用 Neon 無伺服器驅動程式:
- 無法開啟 TCP 連線的邊緣/無伺服器函數
- 受益於資料庫分支(每個 PR 的預覽環境)的應用程式
- 受益於從零擴展的成本敏感工作負載
- 需要連線池的高並發無伺服器應用程式
何時不使用:
- 具有持久連線的長時間運行的伺服器程序(使用標準的
pg搭配 TCP) - 需要透過 PgBouncer 使用會話級別功能(LISTEN/NOTIFY, SET, 臨時資料表)的工作負載
- 需要始終開啟運算且超過 16 CU 的資料庫(高於 16 CU 時無法使用從零擴展)
核心模式
模式 1:使用 neon() 進行 HTTP 查詢
neon() 函數使用 SQL 標記模板建立一個基於 HTTP 的查詢函數。這是進行單次、非互動式查詢的最快路徑。
import { neon } from "@neondatabase/serverless";
const DATABASE_URL = process.env.DATABASE_URL!;
const sql = neon(DATABASE_URL);
// 標記模板 -- 參數會自動參數化(防止注入)
const userId = "abc-123";
const posts =
await sql`SELECT id, title FROM posts WHERE author_id = ${userId}`;
優點: 標記模板會自動參數化值以防止 SQL 注入,HTTP 約 3 次往返 vs WebSocket 約 8 次,無狀態(無需管理連線)
// 錯誤:將 neon() 作為常規函數呼叫(v1.0+ 型別錯誤)
const sql = neon(DATABASE_URL);
const result = await sql(`SELECT * FROM posts WHERE id = ${id}`); // 型別錯誤 + SQL 注入風險
缺點: 從 v1.0 開始,將查詢函數作為常規函數(而非標記模板)呼叫會導致執行時期和型別錯誤——這是特意更改的,以防止因字串插值導致的 SQL 注入
用於動態 SQL 的 sql.query()
當查詢字串在變數中(而非模板字面量)時,使用帶有序號佔位符的 .query() 方法:
const q = "SELECT * FROM posts WHERE id = $1 AND status = $2";
const posts = await sql.query(q, [postId, "published"]);
使用時機: 在執行時期建立的動態 SQL 字串,或儲存在變數中的查詢。參數仍然透過 $1、$2 等方式安全地參數化。
模式 2:可組合的查詢片段
模板查詢支援組合,並在片段間自動重新編號參數。
import { neon } from "@neondatabase/serverless";
const sql = neon(DATABASE_URL);
// 從可重複使用的片段建立查詢
const whereClause = sql`WHERE status = ${'active'} AND role = ${'admin'}`;
const orderClause = sql`ORDER BY created_at DESC`;
const PAGE_SIZE = 20;
const limitClause = sql`LIMIT ${PAGE_SIZE}`;
const users =
await sql`SELECT id, name, email FROM users ${whereClause} ${orderClause} ${limitClause}`;
優點: 參數會在組合的片段間自動重新編號,頁面大小使用命名常數,片段可在多個查詢中重複使用
使用 sql.unsafe() 處理動態資料表/欄位名稱
// 僅用於受信任、已知安全的值——絕不用於使用者輸入
const TABLE_NAME = "posts";
const results =
await sql`SELECT * FROM ${sql.unsafe(TABLE_NAME)} WHERE id = ${postId}`;
使用時機: 僅當您需要插入受信任的標識符(資料表名稱、欄位名稱)而這些標識符無法在 SQL 中參數化時。切勿將使用者提供的值傳遞給 sql.unsafe()。
模式 3:使用 sql.transaction() 進行 HTTP 交易
透過 HTTP 原子性地執行多個查詢,無需 WebSocket 連線。
import { neon } from "@neondatabase/serverless";
const sql = neon(DATABASE_URL);
// 陣列形式——所有查詢在單次 HTTP 往返中執行
const [posts, totalCount] = await sql.transaction([
sql`SELECT id, title FROM posts ORDER BY created_at DESC LIMIT 10`,
sql`SELECT count(*) FROM posts`,
]);
// 帶有交易選項的函數形式
const [, transferResult] = await sql.transaction(
(txn) => [
txn`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`,
txn`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`,
],
{ isolationLevel: "Serializable" },
);
優點: 無需 WebSocket 開銷即可原子執行,陣列形式對於唯讀批次簡潔明瞭,函數形式支援交易選項,隔離級別控制一致性保證
// 錯誤:將相關查詢作為獨立的 HTTP 請求執行
const posts = await sql`SELECT * FROM posts WHERE author_id = ${authorId}`;
const author = await sql`SELECT * FROM users WHERE id = ${authorId}`;
// 兩次獨立的 HTTP 往返,非原子操作,可能出現競爭條件
缺點: 分開的 HTTP 呼叫非原子操作,資料可能在查詢之間發生變化,網路延遲加倍
交易選項
isolationLevel:ReadUncommitted|ReadCommitted|RepeatableRead|SerializablereadOnly:布林值(預設false)deferrable:布林值(預設false,僅與readOnly: true和Serializable同時使用時有效)
模式 4:使用 Pool/Client 的 WebSocket 連線
使用 Pool 和 Client 進行互動式交易或相容 node-postgres API。在無伺服器環境中,必須在單個請求處理器內建立和關閉連線。
import { Pool } from "@neondatabase/serverless";
export async function handleRequest(request: Request): Promise<Response> {
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
try {
// ... 查詢 ...
} finally {
await pool.end(); // 始終在同一個請求中關閉
}
}
關鍵規則: 在處理器內部建立 Pool,在 finally 中使用 pool.end() 關閉。全域 Pool 會導致 WebSocket 連線在無伺服器呼叫之間洩漏。
請參閱 examples/core.md -- 模式 5-7,了解請求範圍的 Pool、互動式交易和 Node.js WebSocket 配置。
模式 5:連線字串設定
Neon 提供兩種連線字串格式:已池化(透過 PgBouncer)和直連。
# 已池化連線(注意:端點 ID 上有 -pooler 尾碼)
# 使用於:無伺服器函數、Web 應用程式、高並發工作負載
DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require
# 直連(無 -pooler 尾碼)
# 使用於:資料庫遷移、pg_dump、LISTEN/NOTIFY、會話級別功能
DIRECT_DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require
優點: 已池化透過 PgBouncer 的交易模式處理多達 10,000 個並發客戶端,直連為管理任務提供完整的會話功能,分開的環境變數使區別明確
PgBouncer 交易模式限制
已池化連線在交易模式下執行 PgBouncer,這意味著連線在每個交易後會返回池中。這會禁止:
SET/RESET語句(改用ALTER ROLE ... SET)LISTEN/NOTIFYWITH HOLD CURSOR- SQL 層級的
PREPARE/DEALLOCATE(支援最多 1,000 個協定層級的預備語句) - 帶有
PRESERVE/DELETE ROWS的臨時資料表 - 會話級別的建議鎖
模式 6:冷啟動和從零擴展處理
Neon 運算資源在 5 分鐘不活動後自動暫停(預設)。冷啟動需要 200-500毫秒。使用適當的逾時和重試邏輯為此進行設計。
const CONNECTION_TIMEOUT_MS = 10_000;
const sql = neon(process.env.DATABASE_URL!, {
fetchOptions: { signal: AbortSignal.timeout(CONNECTION_TIMEOUT_MS) },
});
關鍵規則: 設定明確的逾時時間(10-15秒)以適應冷啟動延遲。使用指數退避重試以確保可靠性。
請參閱 examples/core.md -- 模式 8,了解完整的逾時配置和重試模式。
從零擴展事實
- 預設自動暫停:5 分鐘不活動
- 冷啟動延遲:約 200-500毫秒(因地區和運算大小而異)
- 僅適用於不超過 16 CU 的運算(較大的運算始終保持開啟狀態)
- 付費方案可以調整暫停逾時(最長 7 天)或完全停用
- 活躍的邏輯複製訂閱者會阻止暫停
模式 7:資料庫分支
Neon 分支使用寫時複製語意——分支一個 500GB 的資料庫是即時的,且在資料分歧之前不會分配額外的儲存空間。
# 安裝 neonctl
npm install -g neonctl
# 從 main 建立開發分支
neonctl branches create --name dev-alice --project-id <project-id>
# 建立帶有自動過期時間的分支(用於 CI/預覽)
neonctl branches create --name preview/pr-42 --project-id <project-id> --expires-at "2025-04-01T00:00:00Z"
# 建立僅結構分支(不複製資料——用於敏感環境)
neonctl branches create --name ci-test --schema-only --project-id <project-id>
# 重設開發分支以匹配當前生產環境
neonctl branches reset dev-alice --parent --project-id <project-id>
# 刪除分支
neonctl branches delete preview/pr-42 --project-id <project-id>
優點: 命名分支映射到 git 工作流程,TTL 過期會自動清理 CI 分支,僅結構分支保護敏感資料,重設可使開發與生產同步而無需重建
分支生命週期整合
將分支映射到您的 PR 工作流程:
| 環境 | 分支名稱 | 生命週期 |
|---|---|---|
| 生產 | main | 永久 |
| 開發 | dev-<使用者> | 直到手動刪除 |
| PR 預覽 | pr-<編號> | 與 PR 同時自動刪除 |
| CI 測試 | ci-<執行編號> | 執行完成後 TTL 過期 |
| 臨時測試 | staging-<試驗> | 試驗期間 |
<additional_resources>
其他資源
Neon 控制台
- 專案儀表板: https://console.neon.tech
- 分支管理: 控制台的「分支」標籤頁
- 連線詳細資訊: 控制台的「連線」標籤頁
- 監控: 控制台的「監控」標籤頁(查詢延遲、連線數、運算使用量)
- SQL 編輯器: 控制台內建,適合快速查詢和結構探索
參考資料
- 結構化決策與連線字串速查: reference.md
- 所有核心驅動模式(含完整程式碼): examples/core.md
- 分支與CI/CD工作流程: examples/branching.md
定義
| 術語 | 定義 |
|---|---|
| 計算端點 | 執行 PostgreSQL 的無伺服器運算實例(可暫停/調整大小) |
| 分支 | 使用寫時複製的資料庫快照/副本 |
| 父分支 | 分支從中建立的來源分支 |
| PgBouncer | 交易模式連線池化層(已池化連線字串) |
| CU | 容量單位(1 CU ≈ 0.25 vCPU + 1 GB RAM) |
| DDL | 資料定義語言(CREATE TABLE, ALTER 等) |
| DML | 資料操作語言(SELECT, INSERT, UPDATE, DELETE) |
| 冷啟動 | 運算從暫停狀態喚醒(200-500 毫秒) |
| TTL | 存活時間 — 分支自動刪除前的持續時間(可選) |
Siddharth 用語法
無人使用這個。我們繼續。
</additional_resources>