sql-database-assistant

SQL 数据库助手

类别： 工程 领域： 数据库开发与优化

概述

SQL 数据库助手技能提供了用于分析 SQL 查询性能、从 DDL 文件探索数据库架构，以及根据架构差异生成迁移 SQL 的工具。它帮助团队编写高效查询、维护整洁的架构，并安全地管理数据库演进。

先行确认

开始分析或生成之前，请确认以下输入。如果有任何信息未知或模糊，请先询问，不要自行假设：

• 任务 — 查询优化 / 架构文档编写 / 迁移生成（决定使用哪个脚本）
• SQL 输入 — 要处理的查询、DDL 文件，或源架构与目标架构（脚本的实际输入）
• 目标数据库 / 方言 — Postgres / MySQL / 等（会影响索引建议和迁移 SQL 语法）

停止规则：只询问最可能影响输出的 2-3 项。如果用户说“先起草一下”，则继续处理，并在产物顶部列出假设。

快速入门

# Analyze a SQL query for performance issues
python scripts/query_optimizer.py --file slow_query.sql

# Analyze inline SQL
python scripts/query_optimizer.py --query "SELECT * FROM users WHERE name LIKE '%john%'"

# Explore schema from DDL file
python scripts/schema_explorer.py --file schema.sql

# Generate migration from schema diff
python scripts/migration_generator.py --from old_schema.sql --to new_schema.sql

# JSON output
python scripts/query_optimizer.py --file query.sql --format json

工具概览

query_optimizer.py

分析 SQL 查询中的性能问题和优化机会。

功能	说明
检测 SELECT *	标记选择所有列的查询
缺少索引提示	识别可能需要索引的 WHERE/JOIN 列
检测 N+1	标记相关子查询模式
全表扫描	检测大型表中没有 WHERE 子句的查询
JOIN 分析	检查连接条件和类型
LIKE 优化	标记以通配符开头的 LIKE 模式

schema_explorer.py

根据 SQL DDL（CREATE TABLE）文件生成文档。

功能	说明
表目录	列出所有表及其列数
列详情	记录类型、是否可为空、默认值
索引列表	列出索引及其包含的列
关系映射	识别外键关系
Markdown 输出	生成架构文档

migration_generator.py

通过比较两个架构 DDL 文件生成迁移 SQL。

功能	说明
添加列	为新列生成 ALTER TABLE ADD COLUMN
删除列	为已移除的列生成 ALTER TABLE DROP COLUMN
更改类型	为类型修改生成 ALTER TABLE ALTER COLUMN
新建表	为全新表生成 CREATE TABLE
删除表	为已移除的表生成 DROP TABLE
索引变更	为索引差异生成 CREATE/DROP INDEX

工作流

查询优化工作流

1. 识别慢查询 - 从慢查询日志中收集查询
2. 分析 - 对每个查询运行 query_optimizer.py
3. 审查结果 - 按预估影响确定优先级
4. 优化 - 应用建议的改进
5. 验证 - 重新分析以确认优化效果

架构文档工作流

1. 导出 DDL - 从数据库导出架构
2. 探索 - 运行 schema_explorer.py 生成文档
3. 审查 - 检查关系和数据类型
4. 发布 - 将文档纳入项目文档

迁移工作流

1. 获取当前架构 - 导出当前架构 DDL
2. 定义目标架构 - 编写期望的架构 DDL
3. 生成迁移 - 运行 migration_generator.py
4. 审查 SQL - 检查生成的迁移是否安全
5. 测试 - 先应用到预发布数据库
6. 部署 - 制定回滚方案后应用到生产环境

CI 集成

# Lint SQL queries
python scripts/query_optimizer.py --file queries/ --format json --strict

# Generate schema docs
python scripts/schema_explorer.py --file schema.sql --format markdown > SCHEMA.md

参考文档

• SQL 优化 - 索引策略、查询模式、反模式

常见模式速查

查询反模式

模式	问题	修复方法
SELECT *	获取了不必要的数据	列出具体列
LIKE '%term%'	无法使用索引	使用全文搜索
相关子查询	N+1 查询模式	改写为 JOIN
没有 WHERE 子句	全表扫描	添加筛选条件
WHERE 中使用 OR	索引使用效率低	使用 UNION 或 IN
对索引列使用函数	导致无法使用索引	对值一侧应用函数

索引指南

查询模式	索引类型
WHERE col = value	col 上的 B-tree
WHERE col1 = v AND col2 = v	复合索引（col1，col2）
ORDER BY col	col 上的 B-tree
WHERE col LIKE 'prefix%'	col 上的 B-tree
WHERE col IN (...)	col 上的 B-tree
全文搜索	全文索引

迁移安全

• 始终同时生成回滚 SQL 和正向迁移 SQL
• 使用生产数据副本测试迁移
• 首先将列设为可空，然后回填数据，最后添加约束
• 切勿直接重命名列；应添加新列、迁移数据，再删除旧列