MySQL 数据库助手

快速开始

首次配置

# 1. 复制配置模板
cp config/databases.env.example config/databases.env

# 2. 编辑填入实际数据库信息
# 单数据库：
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=your_database

# 多数据库（加前缀）：
DB1_HOST=localhost  DB1_NAME=db_one
DB2_HOST=remote    DB2_NAME=db_two

# 3. 安装依赖
pip3 install mysql-connector-python

同步表结构

python3 scripts/sync_schema.py            # 同步所有数据库
python3 scripts/sync_schema.py --db DB1  # 只同步 DB1

同步后，references/schemas/{db_name}.md 文件将包含完整的表结构、字段说明、索引、外键信息。

使用模式

模式 A：解释字段关系（使用本地 schema 文件）

读取 references/schemas/ 下对应数据库的 Markdown 文件
基于字段名、类型、外键关系进行分析和解释
用自然语言描述表之间的关联关系

示例用户请求：

"解释 orders 表和 users 表之间的关系"
"user_id 这个字段是外键吗，关联到哪张表"
"这个数据库有哪些核心表"

模式 B：生成 SQL 语句（使用本地 schema 文件）

读取 references/schemas/ 获取表结构上下文
根据用户意图生成准确的 SQL
附上字段说明，解释 SQL 逻辑

示例用户请求：

"查询最近 7 天新注册的用户数量"
"给 products 表添加一个 stock_count INT 字段"
"查询每个用户的订单总金额，按金额降序"
"创建 category 和 product 之间的关联索引"

SQL 生成规范：

SELECT 语句：加 LIMIT 防止全表扫描
ALTER TABLE：使用 ADD COLUMN IF NOT EXISTS（MySQL 8.0+）或先检查再执行
时间查询：使用索引友好的范围条件 created_at >= NOW() - INTERVAL 7 DAY
JOIN：明确写出 JOIN 类型，优先 INNER JOIN

模式 C：生成 ER 图（Mermaid 格式）

# 从本地同步文件生成（推荐）
python3 scripts/generate_er.py

# 指定数据库
python3 scripts/generate_er.py --db skillmarket

# 输出到文件
python3 scripts/generate_er.py --output er.md

# 直接连接数据库生成（不需要先同步）
python3 scripts/generate_er.py --live --db DB1

输出 Mermaid erDiagram 格式，可粘贴到 GitHub/Notion/Typora 等支持 Mermaid 的工具中渲染。

模式 D：直接查询数据库

# 基本查询
python3 scripts/query_db.py --db skillmarket "SELECT COUNT(*) FROM users"

# 查看所有配置的数据库
python3 scripts/query_db.py --list

# 格式化输出
python3 scripts/query_db.py --db DB1 --format json "SELECT * FROM users LIMIT 5"
python3 scripts/query_db.py --db DB1 --format csv "SELECT id, name FROM products"

# 从文件执行 SQL
python3 scripts/query_db.py --db DB1 --file query.sql

# 执行写操作（需要 --write 参数）
python3 scripts/query_db.py --db DB1 --write "INSERT INTO logs(msg) VALUES('test')"

安全说明：默认只允许 SELECT/SHOW/DESCRIBE/EXPLAIN 等只读语句。执行 DDL/DML 需显式加 --write 参数。

Schema 文件说明

references/schemas/{db_name}.md 结构：

# {db_name} 数据库表结构
> 同步时间: 2026-03-20 10:00:00
> 共 N 张表

## 目录
- [表名1](#表名1)
- [表名2](#表名2)

---

## 表名1
**说明**: 表注释

### 字段
| 字段名 | 类型 | 可空 | 键 | 默认值 | 额外 | 注释 |

### 索引
| 索引名 | 类型 | 字段 |

### 外键
| 约束名 | 本表字段 | 关联表 | 关联字段 |

如果 schema 文件不存在，提示用户先运行 python3 scripts/sync_schema.py。

常见问题

连接失败：检查 config/databases.env 中的 HOST/PORT/USER/PASSWORD，确认 MySQL 服务正在运行且网络可达。

schema 文件为空：该数据库可能没有表，或同步时连接失败，重新运行 sync_schema.py 查看错误信息。

生成的 SQL 需要调整：告知具体需求，AI 会基于最新的 schema 重新生成。

mysql-assistant