Skip to content

Releases: FokXuFok/mysql-sql-coach

Release list

v0.1.0 - AI 驱动的 MySQL 慢查询优化教练

v0.1.0 - AI 驱动的 MySQL 慢查询优化教练 Latest
Latest

Choose a tag to compare

View all tags
@FokXuFok FokXuFok released this 12 Jul 17:40
v0.1.0
bec94fd

v0.1.0 - AI 驱动的 MySQL 慢查询优化教练

AI 驱动的 MySQL 慢查询优化教练，输入一条 SQL，自动给出优化建议。

核心功能

  • EXPLAIN 分析：自动连接 MySQL 执行 EXPLAIN，解析执行计划
  • AI 优化建议：调用 DeepSeek / OpenAI / Ollama 分析 SQL，给出问题、优化后 SQL、索引 DDL
  • 性能对比：在数据库中实测优化前后性能，显示提速倍数
  • 交互式选择：用户选 1（原始）或 2（优化后），自动复制到剪贴板
  • 多 AI 模型：支持 DeepSeek、OpenAI、Ollama（本地部署）
  • 降级模式：无数据库时自动降级为 AI 推理模式；--mock 模式无需任何配置
  • 阿里百炼兼容：支持通过阿里百炼 DashScope 调用 DeepSeek 系列模型
  • IDE 友好入口：main.py 提供交互式循环分析，输入 q 退出，适合 PyCharm 等 IDE

两种运行方式

方式一: 命令行 (CLI)

pip install -e .
sql-coach config init    # 生成 .env, 填入 API Key 和数据库连接
sql-coach analyze "SELECT * FROM orders WHERE status='pending'"

分析完成后选 1（原始 SQL）或 2（优化后 SQL），自动复制到剪贴板。

方式二: 交互式入口 (适合 IDE)

python main.py
  • 循环输入 SQL 进行分析
  • 输入 q 退出程序
  • 单条 SQL 失败不会退出, 可继续分析下一条
  • 数据库连不上时自动切换到模拟模式

快速开始

# 1. 安装
pip install -e .

# 2. 生成配置文件
sql-coach config init

# 3. 编辑 .env, 填入 API Key 和数据库连接
#    (参考 .env.example)

# 4a. CLI 方式运行
sql-coach analyze "SELECT * FROM orders WHERE status='pending'"

# 4b. 交互式运行 (PyCharm 推荐)
python main.py

技术栈

组件 技术
CLI click + rich
SQL 解析 sqlparse
数据库 pymysql
AI openai SDK（兼容 DeepSeek/阿里百炼）+ httpx（Ollama）
配置 python-dotenv
测试 pytest + pytest-mock + pytest-cov（82 个测试全通过）

项目结构

sql-coach/
├── sql_coach/
│   ├── ai/           # AI 引擎（DeepSeek/OpenAI/Ollama/Mock + 工厂）
│   ├── db/           # 数据库连接器（MySQL + Mock）
│   ├── engine/       # SQL 解析、EXPLAIN 结果解析
│   ├── report/       # 性能对比、报告格式化
│   ├── models.py     # 数据模型
│   ├── config.py     # 配置加载
│   ├── coach.py      # 主编排服务
│   └── cli.py        # CLI 入口
├── main.py           # IDE 友好的交互式入口
├── tests/            # 82 个测试
├── docker/           # Docker 测试环境 (10 万行数据)
├── .github/workflows/ci.yml  # GitHub Actions CI
├── .env.example      # 配置文件模板
├── README.md         # 项目说明
├── USAGE.md          # 详细使用说明
└── pyproject.toml

.env 配置文件

首次使用运行 sql-coach config init 生成 .env 文件, 然后填入:

配置项 说明
DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME MySQL 连接信息
AI_MODEL AI 模型选择: deepseek / openai / ollama
DEEPSEEK_API_KEY DeepSeek API Key
DEEPSEEK_BASE_URL API 地址 (官方或阿里百炼兼容模式)
DEEPSEEK_MODEL 模型名 (deepseek-chat / deepseek-v4-pro)
BENCHMARK_RUNS 性能对比执行次数

详细配置见 .env.example。

使用示例

$ python main.py

╔══════════════════════════════════════════╗
║   SQL Coach - AI 慢查询优化教练          ║
╚══════════════════════════════════════════╝
输入 SQL 进行分析, 输入 q 退出

> 输入 SQL (或 q 退出): SELECT * FROM commodity WHERE Cname='牛奶'

📋 SQL 优化分析报告
📝 原始 SQL: SELECT * FROM commodity WHERE Cname='牛奶'

📊 执行计划:
  ┌────┬───────────┬──────┬──────┬──────┬─────────────┐
  │ id │ table     │ type │ key  │ rows │ Extra       │
  │ 1  │ commodity │ ALL  │ NULL │ 8    │ Using where │
  └────┴───────────┴──────┴──────┴──────┴─────────────┘

⚠️ 发现 1 个问题:
  🟡 (warning) commodity: 表 commodity 在 Cname 列上缺少索引
      → 在 Cname 列上创建索引以加速查询

📌 索引建议: CREATE INDEX idx_commodity_Cname ON commodity(Cname);

📊 性能对比:
  原始 SQL: 0.000s (扫描 8 行)
  优化 SQL: 0.000s (扫描 8 行)
  提速: 1.6x 🚀

摘要
  优化后 SQL: SELECT * FROM commodity WHERE Cname='牛奶'
  索引建议: CREATE INDEX idx_commodity_Cname ON commodity(Cname);
  提速: 1.6x

> 输入 SQL (或 q 退出): q
已退出 SQL Coach, 再见

测试

  • 82 个单元/集成测试 全部通过
  • 覆盖所有核心模块：解析器、EXPLAIN、AI 引擎、连接器、基准测试、格式化、CLI
  • 端到端集成测试验证完整流程

基础设施

  • Docker 测试环境：10 万行测试数据（users/orders/products）
  • GitHub Actions CI：Python 3.10/3.11/3.12 矩阵测试
  • MIT 许可证

完整更新日志

  • a35be12 feat: add interactive main.py entry with loop + q to exit
  • 97f0dac docs: fix CI badge to point to correct repo
  • bd1ac00 docs: add comprehensive usage guide
  • 72f5958 fix: add MockAIEngine so --mock mode works without API key
  • 296854e fix: provide input to CliRunner in test_cli_analyze_mock_mode
  • f536515 feat: support custom base_url and model name for DeepSeek
  • bec94fd test: add end-to-end integration test
  • 30f1083 docs: add README with usage examples
  • d000f1a ci: add GitHub Actions workflow
  • 23f05db feat: add Docker test environment with sample data
  • a7660b9 feat: add CLI entry with analyze and config commands
  • e764190 feat: add SQLCoach orchestration service
  • 1461905 fix: resolve Rich markup stripping severity labels, strengthen tests
  • f63c281 feat: add Rich-based report formatter
  • 4758542 feat: add SQL benchmark comparison module
  • 09b0169 feat: add mock database connector for fallback mode
  • dbde794 fix: remove DictCursor, add test coverage for DBConnector
  • 7ec3188 feat: add MySQL database connector
  • 6888d27 refactor: fix code quality issues in AI adapters
  • 0061655 feat: add OpenAI and Ollama AI adapters
  • 300a622 feat: add AI engine base and DeepSeek adapter
  • 62d497d fix: recurse into ordering_operation, add grouping_operation, improve test coverage
  • 7ed7a1c feat: add EXPLAIN runner with JSON parsing
  • d4ef929 fix: remove dead code, fix DISTINCT parsing, add empty SQL handling
  • e62b2a6 feat: add SQL parser with sqlparse
  • 4efa650 feat: add configuration loader with .env support
  • c8f65b5 feat: add shared data models
  • 74e61b7 docs: add minimal README for PyPI metadata
  • 783f288 chore: project skeleton with pyproject.toml and config

Full Changelog: https://github.com/FokXuFok/mysql-sql-coach/commits/v0.1.0

Assets 2
Loading