SQL Tutor

sql-query-helper

SQL 查询辅助工具 —— 自然语言→SQL 翻译、查询优化分析、EXPLAIN 执行计划解读。

能力概览

工作流程

自然语言→SQL

1. 使用 schema 命令提取数据库表结构
2. 将 Schema 作为上下文，将用户的自然语言需求翻译为 SQL
3. 使用 optimize 命令检查生成的 SQL 是否有优化空间
4. 使用 explain 命令验证查询执行计划

# 步骤1：提取 Schema（紧凑模式，适合作为 LLM 上下文）
python3 scripts/sql_query_helper.py --db-path data.db schema --compact

# 步骤2：分析 SQL 优化建议
python3 scripts/sql_query_helper.py optimize "SELECT * FROM orders WHERE user_id = 100"

# 步骤3：查看 EXPLAIN 执行计划
python3 scripts/sql_query_helper.py --db-path data.db explain "SELECT * FROM orders WHERE user_id = 100"

Quick Start

Schema 提取

# 提取完整 Schema（JSON 格式，含样本数据）
python3 scripts/sql_query_helper.py --db-path data.db schema

# 紧凑模式（纯文本，适合嵌入 prompt）
python3 scripts/sql_query_helper.py --db-path data.db schema --compact

# 不采样数据
python3 scripts/sql_query_helper.py --db-path data.db schema --sample-rows 0

# PostgreSQL
python3 scripts/sql_query_helper.py --db-type postgres --dsn "host=localhost dbname=mydb user=reader" schema --compact

查询优化分析

# 分析 SQL 查询（无需数据库连接，纯规则检测）
python3 scripts/sql_query_helper.py optimize "SELECT * FROM orders o, users u WHERE o.user_id = u.id"

python3 scripts/sql_query_helper.py optimize "SELECT name FROM users WHERE UPPER(email) LIKE '%@GMAIL.COM'"

python3 scripts/sql_query_helper.py optimize "SELECT id, (SELECT COUNT(*) FROM orders WHERE user_id = u.id) AS order_count FROM users u"

EXPLAIN 解读

# SQLite EXPLAIN
python3 scripts/sql_query_helper.py --db-path data.db explain "SELECT * FROM orders WHERE user_id = 100"

# PostgreSQL EXPLAIN
python3 scripts/sql_query_helper.py --db-type postgres --dsn "host=localhost dbname=mydb" explain "SELECT * FROM orders WHERE user_id = 100"

# PostgreSQL EXPLAIN ANALYZE（实际执行查询，获取真实数据）
python3 scripts/sql_query_helper.py --db-type postgres --dsn "host=localhost dbname=mydb" explain --analyze "SELECT * FROM orders WHERE user_id = 100"

详细用法

全局参数

子命令

schema 参数

explain 参数

优化规则清单

optimize 命令检测以下 13 类 SQL 反模式：

EXPLAIN 解读项

输出示例

schema --compact

-- Database: sqlite
-- users (1500 rows): id INTEGER  PK, name TEXT, email TEXT, age INTEGER, created_at TEXT
--   IDX(unique): idx_users_email on (email)
-- orders (8200 rows): id INTEGER  PK, user_id INTEGER, amount REAL, status TEXT, created_at TEXT
--   FK: user_id -> users.id
--   IDX: idx_orders_user_id on (user_id)

optimize

{
  "sql": "SELECT * FROM orders o, users u WHERE o.user_id = u.id",
  "issues": [
    {
      "severity": "warning",
      "rule": "avoid-select-star",
      "message": "避免 SELECT *：只选择需要的列，减少 I/O 和网络传输",
      "suggestion": "将 SELECT * 改为显式列出需要的列名"
    },
    {
      "severity": "info",
      "rule": "implicit-join",
      "message": "使用了隐式连接（逗号分隔表），可读性差且易出错",
      "suggestion": "改用显式 JOIN ... ON 语法，提高可读性和可维护性"
    }
  ]
}

explain (SQLite)

{
  "db_type": "sqlite",
  "query": "SELECT * FROM orders WHERE user_id = 100",
  "plan": [
    {"id": 2, "parent": 0, "detail": "SEARCH orders USING INDEX idx_orders_user_id (user_id=?)"}
  ],
  "interpretation": [
    {
      "severity": "ok",
      "type": "index-search",
      "detail": "使用索引查找: idx_orders_user_id",
      "suggestion": "索引查找效率良好"
    }
  ]
}

安全机制

• 只读连接：SQLite 使用 ?mode=ro；PostgreSQL 使用 SET SESSION READ ONLY
• SQL 白名单：仅允许 SELECT / WITH / EXPLAIN 开头
• 危险关键字拦截：INSERT、UPDATE、DELETE、DROP 等 30+ 关键字被阻止
• 多语句拦截：禁止分号分隔的多条 SQL
• 标识符转义：表名使用双引号转义，防止 SQL 注入

依赖

• Python 3.8+（sqlite3 为内置模块）
• PostgreSQL 支持需安装：pip install psycopg2-binary
• optimize 命令无需数据库连接，零外部依赖