Metadata-Version: 2.4
Name: dbgenie
Version: 0.1.0
Summary: 用大白话查 MySQL 的命令行 AI 数据库管理员（默认只读）
Author: dbgenie contributors
License-Expression: MIT
Keywords: mysql,ai,nl2sql,cli,database
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymysql>=1.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: readchar>=4.0.0
Requires-Dist: sshtunnel>=0.4.0
Requires-Dist: paramiko<3.5
Requires-Dist: tomli>=2.0; python_version < "3.11"
Dynamic: license-file

# dbgenie

[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/wwhjwd/dbgenie)](https://github.com/wwhjwd/dbgenie)

> 用大白话查 MySQL 的命令行 AI 数据库管理员。终端里连上你的库，直接问「今天的日志有多少条」，它自动翻译成 SQL、执行、把结果回显给你。**默认只读，绝不误写。**

## 为什么做 dbgenie

查数据库一直有个尴尬的门槛：会写 SQL 的人不多，会的人又常被"字段名记不住、多表 JOIN 想不清"拖慢。于是大家要么打开臃肿的可视化工具点点点，要么追着 DBA 帮忙导数据。

大模型出现后，「说人话、出 SQL」本该顺理成章，但市面上的 NL2SQL 工具大多绑在网页里、要上传数据库账号、结果外发，对生产库既不顺手也不放心。

dbgenie 想做的是一件更克制的事：**在你自己终端里，说一句话，得一条结果**——不离开命令行、不把数据交给第三方的中间层，并且默认只读，再手滑也写不坏库。

最低门槛：一条 `pip install`，配好连接，就能和你的 MySQL 用中文聊起来。

## 目录

- [特性](#特性)
- [快速开始](#快速开始)
- [安装](#安装)
- [配置](#配置)
- [多语言](#多语言)
- [支持的模型](#支持的模型)
- [安全说明](#安全说明)
- [常见问题 FAQ](#常见问题-faq)
- [更新日志](#更新日志)
- [开发](#开发)
- [协议](#协议)

## 特性

- 🗣️ **自然语言 → SQL**：中文大白话直接问
- 🔌 **模型可换**：DeepSeek / 智谱 / 豆包 / 千问 / OpenAI / 本地 Ollama（统一 OpenAI 兼容接口，改一行配置即可换脑）
- 🛡️ **默认只读**：白名单校验 + 自动 LIMIT 兜底，绝不误写
- 🔐 **安全模式**：SSH 密钥登录 + 最小权限专用账号，逐步引导、可增删账号、可切换连接
- 🌐 **中英双语**：默认跟随系统语言，`/lang` 一键切换
- 🎨 **现代终端**：rich 渲染彩色表格 / SQL 高亮 / 输入历史
- 🚀 **易分发**：`pip install` 或 Docker

## 快速开始

```bash
# 首次运行：没有配置会自动进引导（①连库 ②选模型 ③输 Key）
dbgenie

# 之后每次直接聊；想改配置再跑这个
dbgenie init
```

进去后：

```
你> 今天的日志有多少条
SQL> SELECT COUNT(*) FROM logs WHERE FROM_UNIXTIME(created_at, '%Y-%m-%d') = CURDATE()
┌──────────┐
│ COUNT(*) │
├──────────┤
│      128 │
└──────────┘
返回 1 行，耗时 0.32s
```

支持的命令：`/help`、`/menu`、`/setup`、`/mode`、`/lang`、`/schema`、`/quit`。也可以直接粘贴只读 SQL（SELECT / SHOW / DESCRIBE）绕过模型直接执行。输入 `↑` 可翻上一条问题。

## 安装

要求 Python 3.9+（建议 3.11+）。

```bash
pip install .
```

安装后即可使用 `dbgenie` 命令（也可 `python -m dbgenie`）。

> Windows 中文若乱码：先 `chcp 65001`（新版已自动把控制台输出改成 UTF-8，一般不用管）。

## 配置

配置文件默认位置：

- Linux/macOS：`~/.config/dbgenie/config.toml`
- Windows：`%APPDATA%\dbgenie\config.toml`

配置文件里有两套连接（`[normal]` 普通 / `[secure]` 安全）+ 一个 `conn_mode` 指针决定用哪套，其余（模型、Key、行数、读写模式、语言）共用。可用 `/setup` 里的「切换连接模式」一键切换。

可用环境变量覆盖（优先级高于配置文件）：

| 环境变量 | 含义 |
|---|---|
| `DBGENIE_DB_HOST` / `DBGENIE_DB_PORT` / `DBGENIE_DB_USER` / `DBGENIE_DB_PASSWORD` / `DBGENIE_DB_NAME` | 数据库连接 |
| `DBGENIE_LLM_BASE_URL` / `DBGENIE_LLM_API_KEY` / `DBGENIE_LLM_MODEL` | 模型连接 |
| `DBGENIE_CONFIG` | 指定配置文件路径 |
| `DBGENIE_LANG` | 界面语言 `zh` / `en` |

配置示例见 `config.example.toml`。

## 多语言

默认跟随系统语言（中文系统中文、英文系统英文）。需要切换时：

- 运行时输入 `/lang`（即时生效并写入配置）；
- 或启动时 `dbgenie --lang en`；
- 或设环境变量 `DBGENIE_LANG=en`。

## 支持的模型

| 预设 | 提供商 | base_url |
|------|--------|----------|
| deepseek | DeepSeek | `https://api.deepseek.com` |
| zhipu | 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` |
| doubao | 豆包（火山方舟） | `https://ark.cn-beijing.volces.com/api/v3` |
| qwen | 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| openai | OpenAI | `https://api.openai.com/v1` |
| ollama | 本地 Ollama | `http://localhost:11434/v1` |

Claude（Anthropic）接口格式不同，可走自建 New-API 中转统一成 OpenAI 格式接入。

## 安全说明

只读由三层保障：

1. **代码层**：SQL 白名单（SELECT/WITH/SHOW/DESCRIBE/EXPLAIN）+ 关键字黑名单 + 拦截多语句 / `INTO OUTFILE` / MySQL 可执行注释 `/*!...*/`
2. **账号层**：建议单独建一个只有 SELECT 权限的 MySQL 账号给 dbgenie 用
3. **兜底层**：SELECT 自动补 `LIMIT`（默认 100 行，可设 0 不限制），防止大表全扫

另有**安全模式**（`dbgenie init` 里选），面向生产环境逐步引导：

- SSH 密钥登录（免密、防爆破），而非密码；
- 最小权限专用账号（只授权查/增/改/删，不给 DDL），并限定 `@'127.0.0.1'` 只能经本机隧道访问；
- `/setup` 里可「切换连接模式」「删除专用账号」，建账号的 SQL 带 `IF [NOT] EXISTS` 可重复跑。

⚠️ 查询时会把**表结构**和**你的问题**发给所配置的模型提供商；查询结果默认只在本地回显、不再外发。敏感数据建议走本地 Ollama 或自建中转。

## 常见问题 FAQ

**Q1：连不上数据库怎么办？**
先分清卡在哪一层——错误提示会明确告诉你：
- 「SSH 主机地址解析不了 / 连不上」→ 服务器 IP 或 22 端口问题；
- 「SSH 认证失败 / 登录被拒」→ 密码错，或公钥没装到服务器 `~/.ssh/authorized_keys`；
- 「数据库拒绝登录 (1045)」→ MySQL 用户名/密码错；
- 「数据库名不存在 (1049)」→ 库名填错。

**Q2：怎么换模型？**
跑 `dbgenie init` 重选，或直接改 `config.toml` 的 `[llm]` 段（base_url / api_key / model）。六家预设见上表。

**Q3：我的数据会不会泄露？**
查询时会把**表结构**和**你的问题**发给模型提供商（这是 NL2SQL 的固有代价）；查询结果只在你本地终端回显，不再外发。敏感数据建议本地 Ollama 或自建中转。

**Q4：能查超过 100 行吗？**
默认 SELECT 自动补 `LIMIT 100`。改 `config.toml` 里 `[security]` 的 `row_limit = 0` 即不限制。

**Q5：会不小心把库删了吗？**
不会。默认只读，`DROP`/`CREATE`/`ALTER` 等 DDL 在任何模式下都被拦截；即使切到读写模式，`UPDATE`/`DELETE` 也必须带 `WHERE`。

**Q6：支持哪些数据库？**
目前只支持 MySQL。其他数据库需自行扩展 `dbgenie/db.py` 的方言差异（SQL 标准语句大多通用）。

## 更新日志

### v0.1.0（初始版本）

- 自然语言 → SQL：中文大白话直接查询
- 默认只读安全阀：白名单 + 关键字黑名单 + 自动 LIMIT 兜底
- 安全模式：SSH 密钥登录 + 最小权限专用账号 + 普通/安全两套连接一键切换
- 中英双语：默认跟随系统语言，`/lang` 切换
- 6 家模型预设（DeepSeek / 智谱 / 豆包 / 千问 / OpenAI / Ollama）
- rich 彩色表格、SQL 高亮、输入历史

## 开发

```bash
pip install -e .
python tests/test_guard.py    # SQL 安全阀自测（含 /*! 注释、WITH...DML）
python tests/test_safety.py   # 安全模式向导 / 账号增删 / 连接切换自测
# 或一条命令跑全部：pytest
```

## 协议

MIT
