前言¶

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