Communitygithub.com

agents-inc/skills

無伺服器 PostgreSQL,支援分支、自動擴展及邊緣相容驅動程式

skills 是什麼?

這是一個專為邊緣運算和無伺服器環境設計的 PostgreSQL 解決方案技能,核心圍繞 Neon 及其 `@neondatabase/serverless` 驅動程式。它指導開發者如何根據情境選擇最佳資料庫連線方式:對於單次查詢,推薦使用基於 HTTP 的 `neon()` 函數以獲得最快的速度和無狀態優勢;對於需要互動式交易的場景,則使用 WebSocket 的 `Pool`/`Client`。此技能重點強調了連線字串的正確配置(例如添加 `-pooler` 尾碼以使用 PgBouncer 的連線池),以應對高併發的無伺服器工作負載,並嚴格限制僅在資料庫遷移等操作時使用直連。此外,它深入介紹了 Neon 的資料庫分支功能,利用寫時複製 (copy-on-write) 機制實現即時且低成本的開發/預覽環境創建,以及如何處理至關重要的冷啟動問題(從零擴展約需 200-500 毫秒喚醒時間),包括設定適當逾時和重試邏輯。整體而言,此技能提供了一套在無伺服器和邊緣運算領域中,高效、安全地使用 PostgreSQL 的完整最佳實踐模式集。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-baas-neon

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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/Client WebSocket 連線
  • 已池化(-pooler)與直連字串,以及何時使用
  • 資料庫分支(開發分支、PR 預覽分支、僅結構分支)
  • 從零擴展行為、冷啟動緩解和自動擴展
  • 用於非互動式 HTTP 交易的 sql.transaction()
  • 用於程式化分支管理的 Neon API 和 neonctl CLI

何時不使用:

  • 傳統的長生命週期伺服器連線(使用標準的 pg 驅動程式搭配 TCP)
  • 複雜的 ORM 特定模式(使用您 ORM 自己的技能)
  • 一般的 PostgreSQL 查詢語法(使用 SQL/Postgres 技能)

詳細資源:

  • 有關決策框架和快速查閱表,請參閱 reference.md

驅動程式與查詢:

  • examples/core.md -- 驅動程式設定、HTTP 查詢、WebSocket 連線、交易

分支與操作:


理念

Neon 將 PostgreSQL 的儲存和運算分離,實現了傳統 Postgres 無法實現的無伺服器功能:從零擴展、即時分支和自動擴展。@neondatabase/serverless 驅動程式用 HTTP 和 WebSocket 取代 TCP,使 Postgres 能夠在缺乏 TCP 支援的邊緣執行時期中存取。

核心原則:

  1. HTTP 追求速度,WebSocket 追求會話 -- neon() 函數使用 HTTP 請求(約 3 次往返)進行單次查詢。當需要會話或互動式交易時,Pool/Client 使用 WebSocket(約 8 次往返)。為工作選擇合適的傳輸方式。
  2. 預設使用連線池 -- 已池化的連線透過 PgBouncer(交易模式)路由,可處理多達 10,000 個並發客戶端。直連受運算大小限制(100-4,000),僅應用於需要會話狀態的遷移或功能。
  3. 分支成本低廉 -- 寫時複製意味著對 500GB 資料庫進行分支,在資料分歧之前不會分配額外的儲存空間。可自由地將分支用於開發、預覽、測試和 CI。
  4. 從零擴展是預設行為 -- 運算資源在閒置 5 分鐘後暫停。冷啟動需要 200-500毫秒。透過設定逾時、重試和連線池來為此進行設計。
  5. 內建 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 | Serializable
  • readOnly:布林值(預設 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 / NOTIFY
  • WITH 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 編輯器: 控制台內建,適合快速查詢和結構探索

參考資料

定義

術語定義
計算端點執行 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>

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

相關技能