前言¶

Serverless Postgres 的賬單裏，除了計算與存儲，網絡數據傳出（egress）往往會在流量放大後突然顯眼：應用每次從數據庫拉回的行數、列寬和調用頻率，會直接疊成「爲什麼 Neon 賬單這麼高」這類問題。手工翻 pg_stat_statements、再對照代碼裏的 ORM 查詢，通常要耗掉大半天。下面介紹 Neon 官方 Agent Skills 倉庫裏的 neon-postgres-egress-optimizer：它把「定位高傳出查詢 → 對照代碼反模式 → 改查詢 → 驗證」寫成固定流程，交給編碼助手按步驟執行。

這是什麼¶

neon-postgres-egress-optimizer 是 Neon agent-skills 下的專項 Skill，維護方與 Neon 文檔、CLI 技能體系一致（在 officialskills.sh 亦有收錄）。

一句話定位：在代碼庫中診斷並修復導致 Postgres 嚮應用側傳出過多數據的查詢模式。官方說明指出，多數高額 egress 來自「應用取回的數據多於實際使用」——例如寬列全表掃、無分頁列表、高頻讀靜態配置、在應用裏做本應在 SQL 完成的聚合，以及 JOIN 導致父表寬列在子行上重複傳輸。

Skill 要求先使用父級 neon Skill 瞭解 Neon 概覽與開發實踐；若未安裝，可從文檔拉取或執行：

neon skills -s neon -y

父 Skill 文檔地址：https://neon.com/docs/ai/skills/neon/SKILL.md。

核心功能¶

資料中的工作流按順序四步：diagnose（診斷）→ analyze（分析代碼）→ fix（修復）→ verify（驗證傳出是否下降且功能未壞）。核心能力均可從官方 SKILL 正文覈對，主要包括：

1. 用 pg_stat_statements 找高傳出候選
   檢查擴展是否可用、在 Neon 上必要時 CREATE EXTENSION；處理計算實例縮容至零後統計被清空的情況（重置統計、代表性流量跑夠時間窗口後再查）。提供多組診斷 SQL：按總返回行數、單次平均行數、調用次數、總執行時間排序的 Top 查詢。

2. 解讀結果時的 egress 優先級
   高行數 + 寬列（JSONB、TEXT、BYTEA 等）優先；極高頻的小查詢也會累積；結合 schema 判斷列寬。

3. 代碼側檢查清單
   是否只 SELECT 需要的列、是否有 LIMIT/分頁、是否適合緩存、是否在應用內聚合、JOIN 是否重複父表數據。

4. 針對常見反模式的修復指引（含前後 SQL 示例）
   - SELECT * → 顯式列名
   - 無分頁列表 → ORDER BY + LIMIT/OFFSET（並提醒 API 是否已支持分頁參數）
   - 高頻靜態數據 → 應用與數據庫之間加緩存
   - 應用側聚合 → GROUP BY 等下推到 SQL
   - JOIN 寬父表重複傳輸 → 拆成兩次查詢分別取父、子表

觸發場景（來自 Skill description）：高額數據庫賬單、意外數據傳輸費用、egress 尖峯、優化 SELECT *、減少從庫到應用的數據量，或在未明說 egress 時審查查詢成本效率。

安裝與啓用¶

在支持 Agent Skills 的助手環境中，可從 Neon 的 agent-skills 倉庫安裝單個 Skill。 officialskills.sh 給出的命令爲：

npx skills add https://github.com/neondatabase/agent-skills --skill neon-postgres-egress-optimizer

亦可把 Skill 目錄鏈接交給助手安裝：

https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres-egress-optimizer

Neon CLI 側安裝的是父級 neon Skill（見上文 neon skills -s neon -y）；專項 egress Skill 以 GitHub / npx skills add 路徑爲準。各 IDE（Cursor、Codex CLI、Claude Code）若已支持同一 Skills 規範，通常共用上述安裝方式；資料未單獨列出差異時，以你當前工具的 Skills 文檔爲準。

典型用法¶

啓用 Skill 後，用自然語言描述賬單或傳出問題即可；助手應按官方四步推進。下面摘錄資料中可復現的診斷段（修復段邏輯相同，按 Step 3 反模式選用）。

1. 確認 pg_stat_statements

SELECT 1 FROM pg_stat_statements LIMIT 1;

若報錯則創建擴展：

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Neon 默認可用該擴展，但仍可能需要上述 CREATE EXTENSION。

2. 統計爲空或實例剛喚醒時

1. SELECT pg_stat_statements_reset();
2. 讓應用在代表性流量下運行至少約一小時。
3. 再執行診斷查詢。

若無生產庫統計權限，可跳過到代碼分析；官方說明代碼層模式常足以定位最嚴重的問題。

3. 找出傳出貢獻最大的查詢（示例：總返回行數 Top 10）

SELECT query, calls, rows AS total_rows, rows / calls AS avg_rows_per_call
FROM pg_stat_statements
WHERE calls > 0
ORDER BY rows DESC
LIMIT 10;

同類還有按 avg_rows_per_call、calls、total_exec_time 排序的查詢，均在官方 SKILL 中給出。

4. 對照代碼並套用修復模板

例如將無分頁列表改爲有界結果集：

SELECT id, name, price FROM products
ORDER BY id
LIMIT 50 OFFSET 0;

或將應用內全表拉取再聚合，改爲 SQL 聚合（資料示例）：

SELECT p.category_id,
       AVG(r.rating) AS avg_rating,
       COUNT(r.id) AS review_count
FROM reviews r
INNER JOIN products p ON r.product_id = p.id
GROUP BY p.category_id;

JOIN 導致父表寬列重複時，資料建議拆成兩次查詢，分別按 products.id 與 reviews.product_id 取值，避免單行請求傳出父表 JSONB 等寬字段 × 子行數倍。

適用場景與注意¶

適合誰

• 使用 Neon Serverless Postgres，賬單或監控裏出現數據傳輸、egress 相關異常。
• 需要把「Neon 賬單尖峯」追到具體未分頁接口、SELECT *、高頻配置查詢等。
• 希望在代碼審查階段就按成本效率看查詢，而不必等用戶口頭提到 egress。

限制與注意

• 診斷依賴 pg_stat_statements；Neon 計算縮容重啓會清空統計，需要按官方步驟重置並等待足夠觀測窗口。
• 分頁、緩存等改動需確認客戶端與 API 契約；Skill 正文已提醒檢查消費方是否支持分頁響應。
• 無分頁列表即使當前表很小也應標記爲風險——規模上來後單次請求傳出會線性惡化。
• 務必與父級 neon Skill 配合，避免在不瞭解 Neon 運維與最佳實踐時孤立改 SQL。

結尾¶

neon-postgres-egress-optimizer 把 Serverless 數據庫裏「傳出成本」這一交叉議題，收斂成可重複的診斷 SQL、解讀規則和修復清單，適合交給 AI 助手在真實代碼庫裏逐步落地。官方 Skill 目錄：

https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres-egress-optimizer