sql-optimization-patterns

sql-optimization-patterns 技能概览

sql-optimization-patterns 能做什么

sql-optimization-patterns skill 适合用来定位慢 SQL、解释查询为什么慢，并围绕查询写法、索引、JOIN、分页以及执行计划解读给出可落地的优化建议。它最有价值的场景，是你已经遇到了真实的性能问题，希望按一套结构化优化流程来处理，而不是只得到泛泛的“加个索引试试”这类建议。

谁适合安装

这个 skill 适合后端工程师、数据库工程师、平台团队，以及不想靠猜来加速查询的应用开发者。它尤其适合在使用 PostgreSQL 风格 EXPLAIN 输出的团队里使用，不过其中的分析思路同样可以迁移到其他关系型数据库。

典型要解决的实际问题

大多数用户需要的，不只是语法层面的检查，还包括：

• 找出查询变慢的真正原因
• 把执行计划中的异常现象映射到可能的根因
• 在改写查询和调整索引之间做判断
• 避免“这个查询快了，但写入变差、存储膨胀”的伪优化
• 把性能取舍清楚地同步给团队

这也是为什么 sql-optimization-patterns 比普通提示词更有用。

这个 skill 的差异点

它最大的区别在于采用了“优化模式”导向的分析框架。它不只是告诉你“去优化 SQL”，而是会把 agent 的注意力拉回到数据库工程里真正关键的问题上，例如：

• 如何解读 EXPLAIN 和 EXPLAIN ANALYZE
• 如何识别顺序扫描、不合理的 JOIN 选择和低效分页
• 如何有意识地制定索引策略
• 如何处理 N+1 访问模式这类常见反模式

最适合与不太适合的场景

最适合：

• 已经确认存在慢查询
• 你能贴出对应的查询计划
• 有 schema、索引和大致行数这类上下文
• 性能问题直接关联 API 延迟或数据库负载

不太适合：

• 没有查询文本
• 没有执行计划
• 纯 ORM 架构层面的讨论，完全看不到 SQL
• 依赖数据库引擎内部细节、而提示里又没提供这些信息的厂商特定调优问题

如何使用 sql-optimization-patterns skill

sql-optimization-patterns 的安装上下文

仓库没有在 SKILL.md 里提供单独的自定义安装器，所以应通过你现有的 skill 加载流程为 wshobson/agents 仓库完成安装，然后确认 agent 能访问名为 sql-optimization-patterns 的 skill。

如果你的环境走的是常见的 Skills 流程，最实用的做法就是先把仓库加入，再在任务里通过 skill 名称显式调用它，并明确说明要做 SQL 优化分析。

先看这个文件

优先阅读：

• plugins/developer-essentials/skills/sql-optimization-patterns/SKILL.md

这个 skill 是自包含的。技能目录下没有额外的 references/、rules/ 或脚本文件，所以大部分可用信息都集中在这一个文件里。好处是上手快，但也意味着你的输入质量会更直接地影响输出质量。

sql-optimization-patterns 需要哪些输入

想让输出足够可靠，最好给 agent 提供：

• SQL 查询本身
• 数据库引擎及版本（如果已知）
• 表结构或相关字段信息
• 当前已有索引
• 行数规模或大致表大小
• EXPLAIN 或 EXPLAIN ANALYZE 输出
• 业务目标，例如“把 P95 接口延迟降下来”

如果没有计划数据，agent 仍然能给出一些模式层面的建议，但可信度会明显下降。

最小可用提示词

一个可用的 sql-optimization-patterns usage 提示词大致可以这样写：

Use the sql-optimization-patterns skill.

Database: PostgreSQL 15
Goal: reduce this query from 2.4s to under 200ms
Tables:
- users(id, email, created_at, status)
- orders(id, user_id, order_total, created_at)

Current indexes:
- users_pkey(id)
- orders_user_id_idx(user_id)

Query:
SELECT u.*, o.order_total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.created_at > NOW() - INTERVAL '30 days'
ORDER BY u.created_at DESC
LIMIT 100;

EXPLAIN ANALYZE:
[paste full plan]

Please identify likely bottlenecks, explain the plan, recommend query/index changes, and rank fixes by expected impact and risk.

如何把模糊请求变成高质量请求

弱请求：

Make this SQL faster.

强请求：

Use sql-optimization-patterns for Database Engineering.

I need:
1. plan interpretation
2. likely root cause
3. index recommendations with rationale
4. query rewrite options
5. tradeoffs for write amplification and storage
6. a safe rollout order

Engine: PostgreSQL 14
Traffic pattern: read-heavy API endpoint
Data scale: users 8M rows, orders 120M rows
Current problem: endpoint P95 is 1.8s, DB CPU spikes during peak
Query: [paste]
Plan: [paste]
Existing indexes: [paste]

第二种写法更有效，因为它给了 skill 足够多的运行上下文，能帮助它做优先级判断，而不是只罗列一堆通用建议。

能拿到最佳结果的实用工作流

推荐这样使用：

1. 贴出准确的查询语句和完整执行计划
2. 先让 agent 用通俗语言解释最主要的成本来源
3. 要求给出 2–3 个候选优化方案，而不是 10 个
4. 让它说明每个方案的预期收益和代价
5. 先实施风险最低的改动
6. 重新跑一次 EXPLAIN ANALYZE
7. 对比优化前后差异

这样能让 sql-optimization-patterns 始终围绕可测量结果工作，而不是停留在推测性调优上。

sql-optimization-patterns 特别擅长什么

从原始内容来看，这个 skill 重点强调：

• EXPLAIN 解读
• 索引策略
• JOIN 模式分析
• 分页效率
• N+1 查询问题

这意味着它非常适合做查询级优化和 schema / 索引决策，而不只是帮你“改改 SQL 写法”或格式化语句。

建议明确提出的请求

如果希望 sql-optimization-patterns install 和后续使用阶段产出更有价值，可以直接让 agent 回答这些问题：

• “这个执行计划里最大的单点瓶颈是什么？”
• “第一步更该加新索引，还是改写查询？”
• “当前有哪些 scan / join 类型在拖慢性能？”
• “这个查询有没有机会变成 index-only？”
• “这个改动会怎样影响写入、vacuum 或存储？”
• “上线后应该重点观察哪些指标？”

这些问法会强迫输出进行优先级排序，这往往就是“有帮助”和“信息噪声”之间的差别。

落地过程中常见的阻碍

真正最常见的阻碍通常不是安装本身，而是证据不完整：

• 只给了部分执行计划
• 没有表大小信息
• 没列出现有索引
• 贴的是 ORM 生成的 SQL，但没有业务背景
• 问的是“最佳实践”，而不是某条真实慢路径

如果你只提供查询文本，得到的大概率是宽泛建议；如果你提供计划、schema 和负载上下文，这个 skill 才会真正变成能支持决策的工具。

如何更安全地解读输出

不要把每个建议的索引都当成“白捡的性能提升”。更稳妥的 sql-optimization-patterns guide 使用心态，是逐项验证：

• 过滤条件或 JOIN 条件是否真的匹配建议的索引顺序
• 查询选择性是否足够高，值得使用该索引
• 复合索引是否比多个单列索引更合理
• 这个修复是否只是让一条查询变快，却拖慢了 insert / update

这个 skill 最强的用法，是让它帮你生成可以立刻验证的假设，而不是直接把建议当成最终结论。

sql-optimization-patterns skill 常见问题

如果我本来就懂 SQL，还值得安装 sql-optimization-patterns 吗？

值得，前提是你希望在高压场景下也能稳定输出一致的优化分析。它的价值不在于补 SQL 基础知识，而在于提供一套围绕执行计划、扫描类型、JOIN 和索引选择的结构化分析模式。

这个 skill 对新手友好吗？

总体还算友好，但新手最好结合真实案例来用。把查询文本和 EXPLAIN ANALYZE 输出对照起来看时，这个 skill 的价值会更清晰。如果你刚接触执行计划，可以先让 agent 用通俗语言解释每个关键节点，再开始讨论优化方案。

它比普通 AI 提示词强在哪？

普通提示词很容易产出泛化的调优建议。sql-optimization-patterns skill 则更偏向一套可复用的优化工作流，以及数据库工程里真正重要的信号，尤其是执行计划解读和索引策略判断。

必须是 PostgreSQL 才能用吗？

不需要，但示例明显更偏 PostgreSQL 风格。如果你使用的是 MySQL、SQLite、SQL Server 或其他引擎，记得带上引擎名称和对应的计划输出，这样 agent 才能调整分析思路。

什么情况下不该先用 sql-optimization-patterns？

如果你的主要问题是下面这些，就不建议把它作为第一工具：

• connection pooling
• 没有查询证据的锁竞争
• 数据库之外的基础设施饱和
• 应用层缓存策略缺失
• ORM 使用方式有问题，导致真实 SQL 被隐藏

这些场景下，这个 skill 可能后续仍然有帮助，但不应作为起点。

它能帮助 schema 设计，不只是处理单条慢查询吗？

可以。这个 skill 覆盖了索引策略和可扩展查询模式，因此也能支持 schema 设计决策。不过它在结合访问模式、预期过滤条件、JOIN 方式、排序规则和数据规模时，效果依然最好。

如何改进 sql-optimization-patterns skill 的使用效果

给 sql-optimization-patterns 提供更扎实的证据

想最快提升结果质量，最有效的做法是提供：

• 完整查询文本，而不是转述
• 完整执行计划，而不是只贴前几行
• 在安全前提下提供 EXPLAIN ANALYZE 的真实耗时
• 当前已有索引
• 近似基数和行数规模
• 负载偏读还是偏写

证据越完整，建议越可信，也越不容易出现无关索引。

明确要求输出排序后的建议

当你要求 skill 按以下维度对方案排序时，它会更有用：

• 预期延迟收益
• 实施成本
• 运维风险
• 写入开销
• 可回滚性

这样的排序能帮助团队做动作选择，而不是只收集一堆想法。

强制它做取舍分析

一个常见失败模式是：接受了“读快了”的方案，却引入高昂写入成本或臃肿索引。要改进 sql-optimization-patterns 输出，可以直接追问：

• “这个索引会给 inserts 和 updates 带来什么成本？”
• “会不会产生冗余索引？”
• “相比再加一个索引，分区或改写查询会不会更好？”
• “这里 keyset pagination 会不会比 offset pagination 更合适？”

用优化前后对比形成迭代闭环

拿到第一轮建议后，重新跑计划，并让 skill 比较：

• 原始瓶颈是什么
• 新瓶颈变成了什么
• 哪些地方确实改善了
• 哪些地方仍然昂贵
• 下一步优化是否还值得继续做

这是把这个 skill 从“一次性回答工具”变成“持续优化循环”的最可靠方式。

留意常见失误模式

最常见的问题包括：

• 没有 ANALYZE 数据就开始优化
• 为低选择性过滤条件添加索引
• 忽略 JOIN 顺序和基数估算
• 改写 SQL 后不验证新的执行计划
• 只盯一条查询，却漏掉上游的 N+1 模式

要减少这些错误，可以要求 agent 在给建议前先明确写出它的假设条件。

能提升输出质量的提示词模式

可以使用这样的提示词：

Use the sql-optimization-patterns skill and do not give generic advice.
Base recommendations on the query plan provided.
For each proposed fix, explain:
1. why it should help
2. what plan node it targets
3. what tradeoff it introduces
4. how to validate it after deployment

这种格式会迫使 agent 把每条建议和证据对应起来，而不是泛泛而谈。

如何推动团队采用

如果你希望这个 skill 能在团队里真正用起来，最好把输入模板标准化：

• engine/version
• query
• schema
• indexes
• plan
• table sizes
• target latency
• workload notes

这样能显著降低输入质量波动，让 sql-optimization-patterns for Database Engineering 在故障处理和代码评审中更容易稳定复用。