data-sql-optimization

用途

该技能用于诊断和调优 OLTP 工作负载下的 SQL，主要覆盖 PostgreSQL、MySQL 和 SQL Server，并将 Oracle 与 SQLite 列为次要覆盖对象。适用场景包括：调优查询、阅读执行计划、设计或删除索引、修复锁争用与死锁、处理连接饱和、搭建监控告警、设计分区策略、规划备份恢复，以及进行安全或行级安全（RLS）审查。

明确不在范围内：OLAP 引擎与湖仓调优。涉及 ClickHouse、DuckDB、Doris、StarRocks、Iceberg、Delta Lake 或 Hudi 时，应改用 data-lake-platform。

主要能力

技能提供脚本、模板与参考指南三类资源。

脚本方面：

scripts/pg_slow_query_triage.sql：基于 pg_stat_statements 生成六段式分诊报告，涵盖总时间、平均时间、I/O、方差、缓存命中率以及溢出/规划/WAL。可直接粘贴进 psql 或任意 SQL 客户端，需要 pg_stat_statements 扩展。
scripts/explain_collector.py：通过 psql 采集估算的 JSON 执行计划；使用 --analyze 才会实际执行查询。
scripts/test_explain_collector.py：离线输入、执行模式与 JSON 封装的回归测试。

模板与参考指南按需加载，覆盖：慢查询分诊、执行计划分析、索引模式、查询重写、连接池模式、监控告警、锁分析、分区策略、恢复策略设计、安全审计、RLS、迁移、备份恢复、复制与高可用、SQLite 优化等。

使用方式

分诊可直接粘贴进 psql：

psql "$DATABASE_URL" -f skills/universal/data-sql-optimization/scripts/pg_slow_query_triage.sql

采集估算计划（默认）：

python scripts/explain_collector.py --queries queries.txt --no-analyze --output plans.jsonl

采集实际计划（会执行查询，需先评估副作用）：

DATABASE_URL=postgresql://user:pass@test-db:5432/db python scripts/explain_collector.py --queries queries.txt --analyze --output plans.jsonl

技能建议先收集上下文再提改动：数据库引擎与精确版本、查询文本或工作负载形态、相关模式/索引/估算行数、实际证据（计划输出、等待统计、查询统计或错误文本）、近期变更（模式、配置、部署、流量峰值或数据倾斜）、并发上下文（应用池、服务器池化器、副本拓扑）、成功指标（p95 延迟、CPU、读取、锁时间、错误率或连接数）。缺失时应先索取或使用接入模板。

诊断以估算计划起步，仅在审查语句、函数与触发器后才采集实际计划，因为 ANALYZE 会执行语句，且回滚不会撤销序列变更或外部影响。采集器每行接受一条语句，拒绝内部含分号（包括字面量/注释内）的输入。

各引擎采集命令示例：

-- PostgreSQL：先估算计划，审查后再选择 ANALYZE 执行 EXPLAIN (VERBOSE, FORMAT TEXT) <query>;

-- MySQL：获取 JSON 计划以查看详细成本分解 EXPLAIN FORMAT=JSON <query>;

-- SQL Server：开启 I/O 与 CPU 证据 SET STATISTICS IO, TIME ON; <query>;

技能强调一次只改一个杠杆，并在每步后验证正确性与性能影响；不要凭一次热缓存执行就宣布调优成功，应在同一工作负载窗口记录正确性、p50/p95/p99、逻辑/物理读取、CPU、锁与写入影响，并说明未能测量的指标。

适用场景

慢查询分诊：需要改动前的安全接入。
计划审查：已有 EXPLAIN、EXPLAIN ANALYZE、Query Store 或 Performance Schema 证据。
索引设计或删除：决定新增、重塑、设为不可见或删除索引。
查询重写：查询形态或估算问题是可能瓶颈。
连接饱和：涉及应用池、PgBouncer、RDS Proxy、Supavisor 或 Cloud SQL 池化。
监控告警：需要数据库性能的仪表盘、基线与告警。
锁与死锁：问题是阻塞、死锁或长事务，而非原始查询成本。
分区：保留、裁剪或表增长驱动变更。
备份恢复设计：需要按故障场景映射恢复能力。
安全或 RLS 审查：审查最小权限、SQL 注入控制或租户隔离。

限制与注意事项

覆盖深度：PostgreSQL 覆盖最深，MySQL 与 SQL Server 为主力，Oracle 与 SQLite 为次要。
版本敏感：部分特性有版本门槛（如 PostgreSQL 18 的 skip scan、AIO、uuidv7()、跨 pg_upgrade 保留统计信息）。建议先取用户精确版本（SELECT version() 或 @@version），再确认特性是否 GA，不要为生产推荐仅测试版特性。
MySQL 生产建议使用 LTS 线而非 Innovation 版本；依赖 HyperGraph 优化器前需确认用户版本中是否默认开启。
SQL Server 使用 Query Store 处理计划回归；IQP 特性有不同发布与兼容性前提，推荐前需查 Microsoft 特性矩阵。
顺序扫描、哈希连接、物化、子查询与 CTE 可能是正确选择，重写前需有计划证据。
每新增一个索引都会增加写入与维护工作，需检查重叠索引并衡量写入影响。
开发数据会掩盖生产倾斜与租户热点，需在并发下比较代表性参数。
规划器提示与会话开关是查询、模式与统计检查之后的诊断实验，不要跨引擎迁移提示。
生产变更需按变更类型选择验证与回滚：查询重写、新索引、统计变更、池/配置变更、分区/模式变更各有对应的试验、回滚触发条件与回滚方式。

学习循环

当既往决策或陷阱相关时，若存在 learnings.consolidated.md 则查阅；仅在需要历史或作为可用回退时使用 learnings.md，否则跳过两者。应用后若遇到值得记住的模式、值得预防的错误或令人意外的领域事实，通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的条目，不要修改 SKILL.md 本身。

技能介绍

用途