SQL查询引擎

提供SQL查询编写、性能优化、索引策略、Schema设计与事务管理的全栈指导，支持PostgreSQL数据库。

核心功能: 本技能提供时使用、化工作流场景等能力。

输入参数

参数名	类型	必填	说明
input	string	是	SQL查询引擎处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

专业版增强能力

能力	免费版	付费版
基础功能	支持	支持
SQL查询引擎SQL查询	不支持	支持
SQL查询引擎ema设计与事务管理	不支持	支持
高清分辨率与无损输出	不支持	支持
批量生成与风格预设	不支持	支持
自定义模型微调	不支持	支持

前置条件

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

功能能力

1. 查询编写与优化

sql

-- EXPLAIN ANALYZE 分析查询计划
EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 42;
# ...
-- N+1查询问题修复：子查询改为JOIN
-- 问题：循环中执行N次查询
-- 修复：单次JOIN查询
SELECT u.name, o.order_date, o.total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.id IN (1, 2, 3, 4, 5);
# ...
-- 窗口函数：排名/累计/分桶
SELECT
  product_name,
  category,
  price,
  RANK() OVER (PARTITION BY category ORDER BY price DESC) AS rank_in_category,
  SUM(price) OVER (PARTITION BY category) AS category_total,
  PERCENT_RANK() OVER (ORDER BY price) AS price_percentile
FROM products;
# ...
-- CTE递归查询：组织架构树
WITH RECURSIVE org_tree AS (
  SELECT id, name, parent_id, 1 AS level
  FROM departments WHERE parent_id IS NULL
  UNION ALL
  SELECT d.id, d.name, d.parent_id, ot.level + 1
  FROM departments d
  JOIN org_tree ot ON d.parent_id = ot.id
)
SELECT * FROM org_tree ORDER BY level, name;

2. 索引策略

sql

-- B-Tree索引（默认，适合等值和范围查询）
CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_created_at ON orders(created_at DESC);
# ...
-- 复合索引（注意列顺序：等值→范围）
CREATE INDEX idx_orders_user_date ON orders(user_id, created_at);
# ...
-- 部分索引（仅索引满足条件的行，减少索引体积）
CREATE INDEX idx_orders_active ON orders(user_id) WHERE status = 'active';
# ...
-- 表达式索引（解决函数导致索引失效）
CREATE INDEX idx_users_lower_email ON users(LOWER(email));
-- 现在可以使用：SELECT * FROM users WHERE LOWER(email) = '[e-mail]'
# ...
-- GIN索引（数据库，适合JSONB/全文检索/数组）
CREATE INDEX idx_products_attrs ON products USING GIN(attributes);
SELECT * FROM products WHERE attributes @> '{"color": "red"}';

• 异常时参考错误处理章节进行恢复
• 关键参数: 索引策略 选项
• 处理流程: 接收输入 -> 执行索引策略 -> 返回结果
• 输入: 用户提供索引策略所需的参数和指令

3. Schema设计与规范化

sql

-- 1NF：消除重复组（每列原子值）
-- 2NF：消除部分依赖（非主键列依赖完整主键）
-- 3NF：消除传递依赖（非主键列不依赖其他非主键列）
# ...
-- 反规范化策略：读多写少场景适当冗余
-- 订单表冗余存储用户名（避免每次JOIN users表）
CREATE TABLE orders (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT NOT NULL REFERENCES users(id),
  user_name VARCHAR(100) NOT NULL,  -- 冗余字段
  total DECIMAL(10,2) NOT NULL CHECK (total >= 0),
  status VARCHAR(20) DEFAULT 'pending',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  CONSTRAINT chk_status CHECK (status IN ('pending','paid','shipped','delivered','cancelled'))
);
# ...
-- 分区表（按时间分区大表）
CREATE TABLE events (
  id BIGSERIAL,
  event_time TIMESTAMPTZ NOT NULL,
  event_data JSONB
) PARTITION BY RANGE (event_time);
# ...
CREATE TABLE events_2026_01 PARTITION OF events
  FOR VALUES FROM ('2026-01-01') TO ('2026-02-01');

• 异常时参考错误处理章节进行恢复
• 关键参数: schema设计与规范化 选项
• 处理流程: 接收输入 -> 执行Schema设计与规范化 -> 返回结果
• 输入: 用户提供Schema设计与规范化所需的参数和指令

4. 事务与并发控制

sql

-- 隔离级别
SET TRANSACTION ISOLATION LEVEL READ COMMITTED;   -- 数据库默认
SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;     -- 最高隔离，防幻读
# ...
-- 乐观锁（版本号控制）
UPDATE products SET stock = stock - 1, version = version + 1
WHERE id = 42 AND version = 5;
-- 若affected_rows = 0，说明已被其他事务修改，需重试
# ...
-- 悲观锁（SELECT FOR UPDATE）
BEGIN;
SELECT * FROM accounts WHERE id = 1 FOR UPDATE;
-- 业务逻辑
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
COMMIT;
# ...
-- 死锁避免：固定加锁顺序
-- 事务A: 先锁account 1 再锁account 2
-- 事务B: 先锁account 1 再锁account 2（而非先2后1）

• 异常时参考错误处理章节进行恢复
• 关键参数: 事务与并发控制 选项

5. 高级查询模式

sql

-- UPSERT（存在则更新，不存在则插入）
INSERT INTO users (email, name, updated_at)
VALUES ('[e-mail]', 'Test', NOW())
ON CONFLICT (email) DO UPDATE
SET name = EXCLUDED.name, updated_at = NOW();
# ...
-- LATERAL JOIN（子查询引用外层表）
SELECT u.name, recent_orders.*
FROM users u
LEFT JOIN LATERAL (
  SELECT * FROM orders
  WHERE orders.user_id = u.id
  ORDER BY created_at DESC
  LIMIT 3
) recent_orders ON true;
# ...
-- 交叉表（行转列）
SELECT user_id,
  SUM(CASE WHEN month = 1 THEN amount ELSE 0 END) AS jan,
  SUM(CASE WHEN month = 2 THEN amount ELSE 0 END) AS feb,
  SUM(CASE WHEN month = 3 THEN amount ELSE 0 END) AS mar
FROM monthly_spending
GROUP BY user_id;

• 异常时参考错误处理章节进行恢复
• 关键参数: 高级查询模式 选项
• 处理流程: 接收输入 -> 执行高级查询模式 -> 返回结果
• 输入: 用户提供高级查询模式所需的参数和指令

6. 数据库运维

sql

-- VACUUM ANALYZE（回收空间+更新统计信息）
VACUUM ANALYZE orders;
# ...
-- 查看表大小和索引大小
SELECT
  relname AS table_name,
  pg_size_pretty(pg_total_relation_size(relid)) AS total_size,
  pg_size_pretty(pg_relation_size(relid)) AS table_size,
  pg_size_pretty(pg_indexes_size(relid)) AS index_size
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;
# ...
-- 慢查询日志配置
ALTER SYSTEM SET log_min_duration_statement = 1000;  -- 记录>1秒的查询
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET work_mem = '4MB';
SELECT pg_reload_conf();

使用方法

1. 确认数据库类型（数据库/MySQL/SQLite）
2. 分析表结构和数据量
3. 使用 EXPLAIN ANALYZE 诊断查询性能
4. 根据诊断结果选择优化策略（索引/重写/分区/反规范化）
5. 验证优化效果并评估副作用

使用范例

示例1：慢查询优化

text

输入: SELECT * FROM orders WHERE DATE(created_at) = '2026-07-21' （慢查询5秒）
诊断: DATE()函数导致created_at索引失效，全表扫描
优化: SELECT * FROM orders WHERE created_at >= '2026-07-21' AND created_at < '2026-07-22'
效果: 使用idx_orders_created_at索引，查询时间从5s降至12ms

示例2：索引策略

text

输入: 频繁查询 SELECT * FROM products WHERE category = 'electronics' AND price < 1000
分析: 两个条件都需要索引，category等值+price范围
方案: CREATE INDEX idx_products_cat_price ON products(category, price)
说明: 等值列在前，范围列在后，充分利用复合索引

示例3：N+1问题修复

text

输入: ORM生成100个用户各自查询订单（100+1次查询）
修复: SELECT u.*, o.* FROM users u LEFT JOIN orders o ON u.id = o.user_id WHERE u.id IN (...)
效果: 101次查询合并为1次，响应时间从2s降至80ms

异常恢复流程

错误场景	原因	处理方式
EXPLAIN ANALYZE 显示Seq Scan而非Index Scan	查询条件导致索引失效（函数包裹列/类型不匹配/OR条件）	移除列上的函数（DATE(col)→范围查询），确保比较类型一致，OR改为UNION ALL
INSERT 报 deadlock detected	两个事务以不同顺序锁定相同资源	统一加锁顺序（按主键排序后加锁），缩小事务范围，使用ON CONFLICT替代先查后插
查询使用 LIKE '%keyword%' 全表扫描	前缀通配符无法使用B-Tree索引	使用全文检索（tsvector+GIN索引）或trigram索引（pg_trgm扩展）
索引存在但未使用	统计信息过期或数据分布倾斜	执行 VACUUM ANALYZE tablename 更新统计信息，检查 pg_stats 查看数据分布
SERIALIZABLE 隔离级别下频繁序列化失败	并发冲突率高，风暴	降级为READ COMMITTED+应用层乐观锁，或使用 advisory lock 减少冲突范围
连接池耗尽 "too many connections"	连接泄漏或并发过高	检查应用是否正确释放连接，配置连接池上限（如PgBouncer max_client_conn=100），使用 pg_stat_activity 排查长事务

热门问题

Q1: EXPLAIN ANALYZE 和 EXPLAIN 有什么区别？

EXPLAIN 仅显示查询计划（预估成本），不实际执行查询。EXPLAIN ANALYZE 实际执行查询并显示实际耗时和行数。生产环境慎用 EXPLAIN ANALYZE 执行UPDATE/DELETE（会真实修改数据），可包裹在事务中回滚：BEGIN; EXPLAIN ANALYZE UPDATE...; ROLLBACK;。分析SELECT时优先用 EXPLAIN ANALYZE，因为它显示预估与实际的偏差.

Q2: 复合索引的列顺序如何决定？

列顺序遵循"等值在前，范围在后"原则。例如 WHERE category = 'A' AND price > 100，索引应为 (category, price)——等值条件category先定位到匹配行，再在子集上用price范围扫描。如果反过来 (price, category)，price的范围扫描后还需逐行检查category，效率更低。通用规则：等值列→排序列→范围列.

Q3: 什么时候应该反规范化？

反规范化适用于读多写少、查询性能优先于写入一致性的场景。典型场景：1)频繁JOIN的读路径（冗余存储关联字段）；2)实时统计需求（预计算聚合表）；3)历史快照（订单冗余存储下单时的商品价格）。反规范化的代价是写入时需同步更新冗余字段（可能需要触发器或应用层保证一致性），以及存储空间增加.

Q4: 乐观锁和悲观锁如何选择？

乐观锁适用于读多写少、冲突概率低的场景——通过版本号version字段实现，更新时检查版本，失败则重试。优势是无锁等待、高并发友好。悲观锁（SELECT FOR UPDATE）适用于写多、冲突概率高、一致性要求严格的场景——直接锁定行，其他事务等待。劣势是降低并发度、可能死锁。资金扣减等关键操作通常用悲观锁，用户信息更新等低冲突场景用乐观锁.

Q5: 数据库的MVCC如何影响VACUUM？

数据库的MVCC（多版本并发控制）中，UPDATE/DELETE不立即删除旧数据，而是标记为"死元组"。这些死元组占据磁盘空间，需要VACUUM回收。VACUUM 标记空间可重用，VACUUM FULL 物理回收空间（需排他锁）。配置 autovacuum 自动执行。高写入表需要更频繁的VACUUM，可通过 ALTER TABLE tablename SET (autovacuum_vacuum_scale_factor = 0.05) 调整触发阈值.

Q6: 分区表什么时候用？用什么分区策略？

分区表适用于单表数据量超过1000万行、且查询通常只涉及部分数据的场景。分区策略：1)范围分区（按时间，适合日志/订单等时序数据）；2)列表分区（按地区/类别，适合有明显分类的数据）；3)哈希分区（均匀分布，适合无明显查询模式的超大表）。分区裁剪（partition pruning）确保查询只扫描相关分区，是性能提升的关键。注意：分区键必须是主键的一部分，跨分区查询有额外开销.

注意事项

• 语法以数据库为主，MySQL/SQLite有差异
• 无法连接实际数据库执行验证
• 性能优化建议基于通用模式，实际效果需在真实环境验证
• 分布式数据库（CockroachDB/TiDB）有额外限制
• 存储过程和触发器的深度调试需数据库管理员介入

结果格式

json

{
  "success": true,
  "data": {
    "result": "SQL查询引擎处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "sql"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}

问题处理指引

错误现象	可能原因	诊断步骤	解决方案
查询执行缓慢	索引失效或缺失	使用 EXPLAIN ANALYZE 分析查询计划，检查索引使用情况	重建或添加缺失的索引，优化查询条件
事务无法提交	死锁	使用 pg_stat_activity 查看死锁事务，分析事务加锁顺序	修改事务逻辑，避免死锁，或使用 SELECT FOR UPDATE 加锁策略
数据插入失败	约束违反	检查插入数据是否符合表定义的约束条件	修正数据，确保符合约束条件
备份失败	权限不足或磁盘空间不足	检查备份权限和磁盘空间	修复权限问题，增加磁盘空间
数据恢复失败	备份文件损坏	尝试使用不同的备份工具或版本进行恢复	检查备份文件完整性，重新备份

安全事项

风险项	等级	防护措施	验证方法
SQL注入攻击	高	使用参数化查询，避免拼接SQL语句	定期进行安全审计，使用安全扫描工具
数据泄露	中	实施访问控制，加密敏感数据	定期检查访问日志，使用数据加密工具
未授权访问	高	限制数据库访问权限，使用强密码策略	定期进行权限审计，使用密码管理工具
数据损坏	中	定期备份数据，使用事务确保数据一致性	定期进行数据备份验证，使用数据恢复工具
网络攻击	高	使用防火墙和入侵检测系统，限制数据库访问	定期进行网络安全审计，使用安全扫描工具

创新优势

场景	效率提升量化分析	差异化对比
查询优化	通过使用索引和优化查询条件，将查询时间从5秒减少到0.5秒，效率提升10倍	相比于传统方法，减少了I/O操作和CPU计算时间
索引策略	通过合理设计索引，将查询时间从1分钟减少到1秒，效率提升60倍	相比于不使用索引或使用不当的索引，显著提高了查询性能
Schema设计	通过规范化设计，减少了数据冗余，提高了数据一致性，同时简化了查询逻辑	相比于反规范化设计，降低了数据冗余，但可能牺牲一些查询性能
事务与并发控制	通过合理的事务隔离级别和锁策略，减少了死锁和并发冲突，提高了系统稳定性	相比于不控制事务或使用不当的锁策略，显著提高了系统性能和稳定性
高级查询模式	通过使用窗口函数、CTE等高级查询模式，提高了复杂查询的编写效率，减少了代码复杂度	相比于传统查询方法，提高了查询效率和代码可读性

功能一览

• 自动化执行: SQL查询编写、性能优化、索引策略、Schema设计与事务管理的全栈指导。SQL全栈能力引擎，覆盖查询编写、性能优化、索
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

用户答疑汇总

Q1: SQL查询引擎支持哪些输入格式？

A1: SQL查询编写、性能优化、索引策略、Schema设计与事务管理的全栈指导。SQL全栈能力引擎，覆盖查询编写、性能优化、索引策略、Schema设计、事务管理与。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

量化评估

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

特色对比

对比维度	SQL查询引擎	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	SQL查询编写、性能优化、索引策略、Schema设计与事务管理的全栈指导。SQL	通用场景	通用场景

错误恢复策略

针对SQL查询引擎使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

SQL查询引擎通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent
• 操作系统: Windows / macOS / Linux

可用性分类

• 分类: MD（纯Markdown指令，通过自然语言驱动Agent完成操作）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作。