sql-optimization-patterns

sql-optimization-patterns 技能總覽

sql-optimization-patterns 是做什麼的

sql-optimization-patterns 技能可協助 agent 診斷 SQL 為何變慢、說明查詢慢的原因，並針對查詢寫法、索引、joins、pagination 與 execution plan 判讀提出具體修正建議。當你已經碰到真實的效能問題，想要一套有結構的優化流程，而不是泛泛的「加個索引看看」建議時，它特別有用。

誰適合安裝 sql-optimization-patterns

這個技能很適合 backend engineers、database engineers、platform teams，以及不想靠猜測來把查詢跑快的 application developers。對於使用 PostgreSQL 風格 EXPLAIN 輸出的團隊尤其相關，但其中的判讀與推理模式也能延伸到其他關聯式資料庫。

實際要解決的工作

使用者通常需要的不只是語法檢查，而是要能：

• 找出查詢為什麼慢
• 把 plan 中的症狀對應到可能的根因
• 在 query rewrite 與 index 調整之間做選擇
• 避免用會讓單一查詢變快、卻拖累寫入或增加儲存成本的「修法」
• 清楚向團隊說明取捨與風險

這也是 sql-optimization-patterns 比單純 prompt 更有價值的地方。

sql-optimization-patterns 有什麼不同

它的主要差異在於以「模式」為核心來分析，不是只說一句「優化 SQL」，而是把 agent 導向實務上的 database engineering 重點，例如：

• 判讀 EXPLAIN 與 EXPLAIN ANALYZE
• 找出 sequential scan、不理想的 join 選擇，以及低效率的 pagination
• 有意識地選擇索引策略
• 處理常見 anti-pattern，例如 N+1 存取模式

最適合與不太適合的情境

最適合：

• 已知有一條慢查詢
• 你能貼出查詢 plan
• 手上有 schema、indexes 與 row count 等背景
• 效能工作與 API latency 或資料庫負載直接相關

較不適合：

• 沒有 query text
• 沒有 execution plan
• 純 ORM 層的架構問題，且看不到實際 SQL
• 需要高度依賴特定資料庫引擎內部細節、但 prompt 沒提供資訊的 vendor-specific tuning

如何使用 sql-optimization-patterns 技能

sql-optimization-patterns 的安裝情境

這個 repository 並沒有在 SKILL.md 內提供自訂 installer，因此你需要透過 wshobson/agents repository 的技能載入流程來安裝，並確認 agent 可以存取名為 sql-optimization-patterns 的 skill。

如果你的環境採用常見的 Skills 流程，實務上就是先加入該 repository，之後在任務中用技能名稱呼叫它，並清楚要求進行 SQL optimization analysis。

先讀這個檔案

請先看：

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

這個技能本身是自成一體的。技能資料夾內沒有額外的 references/、rules/ 或 scripts，因此大部分可直接使用的指引都集中在這一個檔案裡。這對快速上手是好事，但也代表你的輸入品質會更直接影響輸出結果。

sql-optimization-patterns 需要哪些輸入

想得到品質較高的輸出，請提供給 agent：

• SQL query
• 資料庫引擎與版本（若知道）
• table schemas 或相關欄位
• 現有 indexes
• row count 規模或大致 table size
• EXPLAIN 或 EXPLAIN ANALYZE 輸出
• 業務目標，例如「把 endpoint 的 P95 latency 降下來」

如果沒有 plan 資料，agent 仍可提出一些模式層級的建議，但可信度會比較低。

最低可用 prompt

一個可用的 sql-optimization-patterns usage prompt 可以長這樣：

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.

如何把模糊需求變成有力的 sql-optimization-patterns 請求

弱的請求：

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]

第二種 prompt 之所以效果更好，是因為它提供了足夠的營運背景，讓技能能先排序真正該做的修正，而不是只丟出一串通用建議。

能拿到最好結果的實務 workflow

一個好用的流程是：

1. 貼上完整且精確的 query 與 full plan
2. 請 agent 用白話解釋最大的成本來源
3. 要求提供 2–3 個候選修法，而不是 10 個
4. 請它說明每個方案的預期收益與代價
5. 先實作風險最低的改動
6. 重新跑 EXPLAIN ANALYZE
7. 比較修改前後差異

這樣能讓技能聚焦在可量測的結果，而不是流於猜測式調校。

sql-optimization-patterns 特別擅長什麼

從原始內容來看，這個技能特別強調：

• EXPLAIN 判讀
• 索引策略
• join pattern 分析
• pagination 效率
• N+1 query 問題

也就是說，它很適合處理 query-level optimization 與 schema/index 決策，而不只是 SQL formatting。

建議明確要求的內容

如果你想讓 sql-optimization-patterns install 與實際使用更有產出，建議明確要求 agent 回答：

• 「這個 plan 裡最大的單一瓶頸是什麼」
• 「第一步應該先加新 index，還是先改寫 query」
• 「哪些 scan/join types 正在拖慢效能」
• 「這條 query 有沒有機會變成 index-only」
• 「這個改動會怎麼影響 writes、vacuum 或 storage」
• 「上線後應該量測哪些指標」

這類問題會迫使輸出做優先級排序，而這通常正是「有幫助」與「很吵但沒決策價值」的差別。

導入 sql-optimization-patterns 時常見的阻礙

最大的阻礙通常不是安裝，而是證據不夠完整：

• 只提供部分 plan output
• 沒有 table size 資訊
• 沒列出目前已有的 indexes
• 貼的是 ORM 產生的 SQL，但沒有業務背景
• 問的是泛泛的「best practices」，而不是實際路徑診斷

如果你只給 query text，預期得到的多半是較寬泛的建議；若能提供 plan、schema 與 workload context，這個技能才會真正變成可拿來做決策的工具。

如何安全解讀 sql-optimization-patterns 的輸出

不要把每一個建議的 index 都當成零成本的勝利。一個好的 sql-optimization-patterns guide 使用心態是先驗證：

• filter 或 join predicates 是否真的符合提議的 index 順序
• query 的 selectivity 是否高到足以受益
• composite index 是否比多個 single-column indexes 更合適
• 這個修法是否只幫到單一 query，卻傷害 insert/update 效能

這個技能最強的用法，是拿它來產生你可以立刻驗證的假設，而不是直接照單全收。

sql-optimization-patterns 技能常見問題

如果我本來就懂 SQL，還值得安裝 sql-optimization-patterns 嗎？

值得，如果你需要在有壓力的情境下持續做出一致的優化分析。它的價值不在基礎 SQL 知識，而是在對 plan、scan type、join 與 index 選擇提供一套結構化的模式。

sql-optimization-patterns 對新手友善嗎？

算是友善，但新手最好搭配真實案例使用。把 query text 與 EXPLAIN ANALYZE 輸出對照著看，這個技能會清楚很多。如果你剛接觸 execution plan，先要求 agent 用白話定義每個重要 node，再請它提出修改建議。

它跟一般 AI prompt 相比好在哪裡？

一般 prompt 常會給出很泛的 tuning 建議。sql-optimization-patterns skill 則是圍繞可重複使用的優化 workflow，以及 database engineering 真正在意的訊號來設計，尤其是 plan interpretation 與 index strategy。

sql-optimization-patterns 一定要搭配 PostgreSQL 嗎？

不一定，但範例明顯偏 PostgreSQL 風格。如果你使用 MySQL、SQLite、SQL Server 或其他引擎，請一併提供引擎名稱與對應的 plan 輸出，讓 agent 能調整建議內容。

什麼情況下不該先用 sql-optimization-patterns？

如果主要問題是以下這些，就不應該先從這裡開始：

• connection pooling
• 沒有 query 證據的 lock contention
• 資料庫以外的 infrastructure saturation
• 缺乏 application caching strategy
• ORM 誤用，導致實際 SQL 被隱藏

這些情況下，這個技能之後可能還是有幫助，但不會是第一個該用的工具。

它能幫 schema design，還是不只處理單一慢查詢？

可以。這個技能涵蓋 indexing strategy 與可擴展的 query patterns，因此也能支援 schema 層級的決策。不過它仍然在和 access patterns、預期 filters、joins、sort orders 與 data volume 綁在一起時最有效。

如何改進 sql-optimization-patterns 技能的使用效果

給 sql-optimization-patterns 更完整的證據

想更快提升結果品質，最直接的方法是提供：

• 完整 query text，而不是轉述
• 完整 plan output，而不是只貼前幾行
• 在安全前提下提供 EXPLAIN ANALYZE 的實際 timing
• 現有 indexes
• 約略的 cardinality 與 row counts
• workload 偏 read-heavy 還是 write-heavy

證據越完整，建議就越可信，也越不容易出現無關緊要的索引建議。

要求輸出做排序

當你要求技能依下列面向幫修法排序時，它會更實用：

• 預期 latency 改善幅度
• 實作成本
• 營運風險
• 寫入額外負擔
• 是否容易回退

這種排序能幫團隊真的做出行動選擇，而不只是蒐集想法。

強制做取捨分析

常見失敗模式之一，是接受了讀取很快、但寫入成本高昂或 index 膨脹的方案。想改善 sql-optimization-patterns 的輸出，可以直接追問：

• 「這個 index 對 inserts 和 updates 的成本是什麼？」
• 「這會不會產生重複或冗餘的 indexes？」
• 「這裡是 partitioning 或 query rewrite 會比再加一個 index 更好嗎？」
• 「這個情境下 keyset pagination 是否比 offset pagination 更合適？」

用前後對照反覆迭代

拿到第一輪建議後，重新跑一次 plan，並請技能比較：

• 原本的瓶頸
• 新的瓶頸
• 哪些地方改善了
• 哪些成本仍然偏高
• 下一步優化是否還值得做

這是把技能變成持續優化迴圈，而不是一次性回答的最可靠方式。

留意常見失敗模式

最常見的錯誤包括：

• 沒有 ANALYZE 資料就開始優化
• 針對低 selectivity filter 新增 indexes
• 忽略 join order 與 cardinality estimates
• 改寫 SQL 後沒有驗證新的 plan
• 只盯著單一 query，卻漏看上游的 N+1 pattern

你可以要求 agent 在提出建議前先明確列出假設，來降低這些錯誤。

能提升輸出品質的 prompt 模式

可以使用像這樣的 prompts：

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 把每一項建議都和具體證據連起來。

改善團隊導入 sql-optimization-patterns 的方式

如果你希望這個技能能在團隊內真正發揮作用，建議把輸入模板標準化：

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

這能降低個案差異，讓 sql-optimization-patterns for Database Engineering 在 incident 與 code review 中都更容易重複套用。