sql-optimization-patterns

Tổng quan về skill sql-optimization-patterns

sql-optimization-patterns làm được gì

Skill sql-optimization-patterns giúp agent chẩn đoán SQL chạy chậm, giải thích vì sao một query bị chậm, và đề xuất cách khắc phục cụ thể xoay quanh cấu trúc query, indexing, joins, pagination, cũng như cách đọc execution plan. Skill này hữu ích nhất khi bạn đã có một vấn đề hiệu năng thực tế và muốn theo một quy trình tối ưu hóa có cấu trúc, thay vì chỉ nhận lời khuyên chung chung kiểu “thêm index đi”.

Ai nên cài skill này

Skill này phù hợp với backend engineer, database engineer, platform team và application developer cần tăng tốc query mà không phải đoán mò. Nó đặc biệt hợp với các team đang làm việc với output EXPLAIN theo kiểu PostgreSQL, nhưng các mẫu tư duy phân tích bên trong vẫn áp dụng tốt cho nhiều hệ quản trị cơ sở dữ liệu quan hệ khác.

Nhu cầu công việc thực tế mà skill giải quyết

Người dùng thường cần nhiều hơn một bài review cú pháp. Họ cần:

• xác định vì sao query chậm
• đối chiếu các dấu hiệu trong plan với nguyên nhân gốc có khả năng cao
• quyết định nên rewrite query hay thay đổi index
• tránh những “cách sửa” giúp nhanh một query nhưng lại làm hại hiệu năng ghi hoặc tốn thêm storage
• truyền đạt rõ ràng các tradeoff cho cả team

Đó là lúc sql-optimization-patterns phát huy giá trị hơn hẳn một prompt thông thường.

Điều gì làm skill này khác biệt

Điểm khác biệt lớn nhất là cách tiếp cận theo pattern. Skill này không chỉ nói “hãy tối ưu SQL”; nó định hướng agent vào những mối quan tâm rất thực tế trong database engineering như:

• đọc EXPLAIN và EXPLAIN ANALYZE
• phát hiện sequential scan, lựa chọn join chưa phù hợp, và pagination kém hiệu quả
• chọn chiến lược index có chủ đích
• xử lý các anti-pattern phổ biến như N+1 access pattern

Trường hợp phù hợp nhất và trường hợp không phù hợp

Phù hợp nhất:

• đã có một query chậm cụ thể
• có query plan để dán vào
• có sẵn thông tin schema, index và quy mô số lượng dòng
• bài toán hiệu năng gắn với độ trễ API hoặc tải của database

Ít phù hợp hơn:

• không có nội dung query
• không có execution plan
• câu hỏi thuần ở tầng ORM architecture mà không nhìn thấy SQL thực tế
• tối ưu đặc thù theo vendor phụ thuộc vào engine internals nhưng không được cung cấp trong prompt

Cách dùng skill sql-optimization-patterns

Ngữ cảnh cài đặt cho sql-optimization-patterns

Repository này không đưa ra trình cài đặt riêng trong SKILL.md, vì vậy hãy cài nó qua quy trình nạp skill của bạn cho repository wshobson/agents, sau đó bảo đảm agent của bạn có thể truy cập skill có tên sql-optimization-patterns.

Nếu môi trường của bạn dùng luồng Skills phổ biến, cách làm thực tế là thêm repository trước, rồi gọi skill theo đúng tên trong một task nêu rõ rằng bạn cần phân tích tối ưu SQL.

Hãy đọc file này trước

Bắt đầu với:

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

Skill này là dạng self-contained. Trong thư mục skill không có references/, rules/ hay script hỗ trợ, nên phần lớn hướng dẫn hữu dụng đều nằm trong đúng file đó. Điều này thuận lợi cho việc triển khai nhanh, nhưng cũng đồng nghĩa chất lượng đầu vào của bạn sẽ ảnh hưởng nhiều hơn đến chất lượng đầu ra.

Skill cần những đầu vào gì

Để có đầu ra mạnh và đáng tin hơn, hãy cung cấp cho agent:

• câu SQL query
• database engine và version nếu biết
• schema bảng hoặc các cột liên quan
• các index hiện có
• quy mô row-count hoặc kích thước bảng ước lượng
• output EXPLAIN hoặc EXPLAIN ANALYZE
• mục tiêu nghiệp vụ, ví dụ như “giảm P95 endpoint latency”

Nếu không có dữ liệu plan, agent vẫn có thể gợi ý theo pattern, nhưng mức độ tin cậy của khuyến nghị sẽ thấp hơn.

Prompt tối thiểu có thể dùng

Một prompt sql-optimization-patterns usage đủ dùng có thể như sau:

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.

Cách biến một yêu cầu sơ sài thành yêu cầu mạnh

Yêu cầu yếu:

Make this SQL faster.

Yêu cầu mạnh:

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 thứ hai hoạt động tốt hơn vì nó cung cấp đủ ngữ cảnh vận hành để skill ưu tiên cách sửa, thay vì chỉ liệt kê mẹo chung chung.

Quy trình thực tế để có kết quả tốt nhất

Một workflow tốt là:

1. dán đúng query và toàn bộ plan
2. yêu cầu agent giải thích các yếu tố gây tốn chi phí nhất bằng ngôn ngữ dễ hiểu
3. yêu cầu 2-3 phương án sửa tiềm năng, không phải 10 phương án
4. yêu cầu nêu rõ mặt lợi và mặt hại kỳ vọng của từng phương án
5. triển khai thay đổi có rủi ro thấp nhất trước
6. chạy lại EXPLAIN ANALYZE
7. so sánh trước và sau

Cách làm này giữ cho skill bám sát kết quả đo được, thay vì trôi sang tối ưu suy đoán.

sql-optimization-patterns đặc biệt mạnh ở đâu

Tài liệu nguồn nhấn mạnh rất rõ các điểm sau:

• diễn giải EXPLAIN
• chiến lược index
• phân tích join pattern
• hiệu quả của pagination
• vấn đề N+1 query

Vì vậy, đây là skill rất hợp cho tối ưu ở cấp query và các quyết định về schema/index, chứ không chỉ đơn thuần là format lại SQL.

Nên yêu cầu rõ điều gì

Để nhận được đầu ra hữu ích hơn trong quá trình sql-optimization-patterns install và sử dụng, hãy yêu cầu agent những điều như:

• “the single biggest bottleneck in this plan”
• “whether a new index or a query rewrite is the better first move”
• “which scan/join types are hurting me”
• “whether the query can become index-only”
• “how this change affects writes, vacuum, or storage”
• “what to measure after rollout”

Các kiểu prompt này buộc agent phải ưu tiên hóa, và đó thường là khác biệt giữa một câu trả lời hữu ích với một câu trả lời nhiều nhưng loãng.

Các vướng mắc thường gặp khi bắt đầu áp dụng

Trở ngại lớn nhất thường không nằm ở cài đặt mà ở việc thiếu bằng chứng:

• chỉ có một phần output plan
• không có thông tin kích thước bảng
• không liệt kê các index hiện tại
• dán SQL do ORM sinh ra nhưng không có ngữ cảnh nghiệp vụ
• hỏi “best practices” thay vì chẩn đoán một đường truy cập thực tế

Nếu bạn chỉ cung cấp phần query text, hãy chờ đợi các gợi ý khá rộng. Nếu bạn cung cấp plan, schema và ngữ cảnh workload, skill này sẽ hữu ích hơn nhiều cho việc ra quyết định.

Diễn giải output một cách an toàn

Đừng xem mọi index được đề xuất như một chiến thắng miễn phí. Khi dùng sql-optimization-patterns guide, tư duy an toàn là phải kiểm chứng:

• predicate trong filter hoặc join có thật sự khớp với thứ tự cột của index được đề xuất hay không
• query có đủ tính chọn lọc để hưởng lợi hay không
• composite index có tốt hơn nhiều index một cột hay không
• cách sửa đó có giúp một query nhưng lại làm chậm insert/update hay không

Skill này mạnh nhất khi được dùng để tạo ra các giả thuyết mà bạn có thể kiểm thử ngay.

Câu hỏi thường gặp về skill sql-optimization-patterns

Có đáng cài sql-optimization-patterns nếu tôi đã biết SQL không?

Có, nếu bạn muốn một quy trình phân tích tối ưu nhất quán khi đang chịu áp lực. Giá trị của skill không nằm ở kiến thức SQL cơ bản; nó nằm ở bộ pattern có cấu trúc xoay quanh plan, scan type, join và lựa chọn index.

Skill này có thân thiện với người mới bắt đầu không?

Khá thân thiện, nhưng người mới nên dùng nó với ví dụ thực tế. Skill này dễ hiểu hơn nhiều khi bạn đặt query text cạnh output EXPLAIN ANALYZE để đối chiếu. Nếu bạn còn mới với execution plan, hãy yêu cầu agent giải thích mọi node quan trọng bằng ngôn ngữ đơn giản trước khi đề xuất thay đổi.

Nó tốt hơn prompt AI thông thường ở điểm nào?

Một prompt thông thường thường chỉ cho ra các mẹo tuning chung chung. sql-optimization-patterns skill được định hướng cho một workflow tối ưu hóa có thể lặp lại và tập trung vào những tín hiệu thực sự quan trọng trong database engineering, đặc biệt là diễn giải plan và chiến lược index.

Có bắt buộc phải dùng PostgreSQL không?

Không, nhưng các ví dụ mang màu sắc PostgreSQL khá rõ. Nếu bạn dùng MySQL, SQLite, SQL Server hoặc engine khác, hãy nêu rõ tên engine và cung cấp output plan tương đương để agent điều chỉnh hướng dẫn cho phù hợp.

Khi nào không nên dùng sql-optimization-patterns?

Không nên bắt đầu từ đây nếu vấn đề chính là:

• connection pooling
• lock contention nhưng không có bằng chứng từ query
• hạ tầng bị bão hòa ở bên ngoài database
• thiếu chiến lược caching ở tầng ứng dụng
• dùng ORM sai cách đến mức che mất SQL thực tế

Trong các trường hợp đó, skill này có thể hữu ích về sau, nhưng không phải công cụ đầu tiên nên dùng.

Skill có giúp thiết kế schema, chứ không chỉ xử lý một query chậm không?

Có. Skill này bao phủ cả chiến lược indexing và các query pattern có khả năng mở rộng, nên có thể hỗ trợ các quyết định về schema. Tuy vậy, nó vẫn hiệu quả nhất khi gắn với access pattern, filter dự kiến, joins, sort order và khối lượng dữ liệu cụ thể.

Cách cải thiện skill sql-optimization-patterns

Cung cấp bằng chứng tốt hơn cho sql-optimization-patterns

Cách nhanh nhất để cải thiện kết quả là cung cấp:

• toàn bộ câu query, không phải bản diễn giải
• toàn bộ output plan, không chỉ vài dòng đầu
• timing thực tế từ EXPLAIN ANALYZE nếu an toàn
• các index hiện có
• cardinality và row count ước lượng
• workload thiên về đọc hay ghi

Bằng chứng tốt hơn sẽ tạo ra khuyến nghị đáng tin hơn và giảm bớt các index không liên quan.

Yêu cầu khuyến nghị có xếp hạng

Skill này hữu ích hơn khi bạn yêu cầu nó xếp hạng các cách sửa theo:

• mức tác động kỳ vọng lên latency
• công sức triển khai
• rủi ro vận hành
• chi phí ghi
• khả năng hoàn tác

Kiểu xếp hạng này giúp team chọn được hành động tiếp theo, thay vì chỉ gom thêm ý tưởng.

Buộc phân tích tradeoff

Một lỗi rất hay gặp là chấp nhận một giải pháp đọc nhanh nhưng làm chi phí ghi tăng mạnh hoặc làm index phình to. Để cải thiện output của sql-optimization-patterns, hãy hỏi:

• “What does this index cost on inserts and updates?”
• “Will this create redundant indexes?”
• “Would partitioning or a rewrite be better than another index?”
• “Is keyset pagination better here than offset pagination?”

Dùng vòng lặp trước-và-sau

Sau khuyến nghị đầu tiên, hãy chạy lại plan và yêu cầu skill so sánh:

• bottleneck ban đầu
• bottleneck mới
• phần nào đã cải thiện
• phần nào vẫn còn đắt
• lần tối ưu tiếp theo có còn đáng làm hay không

Đây là cách đáng tin nhất để biến skill thành một vòng lặp tối ưu hóa, thay vì một câu trả lời dùng một lần.

Theo dõi các failure mode phổ biến

Những lỗi phổ biến nhất là:

• tối ưu khi chưa có dữ liệu ANALYZE
• thêm index cho các filter có độ chọn lọc thấp
• bỏ qua join order và cardinality estimate
• rewrite SQL nhưng không kiểm tra plan mới
• chỉ tập trung vào một query mà bỏ lỡ N+1 pattern ở phía upstream

Bạn có thể giảm các lỗi này bằng cách yêu cầu agent nêu rõ các giả định trước khi đề xuất thay đổi.

Mẫu prompt giúp tăng chất lượng đầu ra

Dùng các prompt như:

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

Định dạng này buộc agent gắn từng đề xuất với bằng chứng cụ thể.

Cải thiện khả năng áp dụng trong team

Nếu bạn muốn skill này hữu ích cho cả team, hãy chuẩn hóa mẫu đầu vào:

• engine/version
• query
• schema
• indexes
• plan
• kích thước bảng
• target latency
• ghi chú về workload

Cách này giúp giảm biến thiên giữa các lần sử dụng và khiến sql-optimization-patterns for Database Engineering trở nên nhất quán hơn nhiều giữa các incident và code review.