dm_ai_analyst v0.0.3

基于 大语言模型 (LLM) 辅助 的智能数据库查询分析工具。

用户以自然语言提出数据分析需求 → 获取数据库 Schema（表结构）→ 借助 LLM 生成 SQL → 人工确认 → 执行查询 → 导出 Excel。

信息	内容
版本	v0.0.3
描述	基于 LLM 辅助的智能数据库查询分析工具
作者	whqtian
Python	>= 3.10
许可证	MIT

🚀 当前状态：数据库连接管理、SQL 安全校验、Schema 获取、查询执行与 Excel 导出等基础设施已完成， LLM 集成（自然语言 → SQL 自动生成 + SQL 执行错误自动修正）已就绪，配置 API Key 即可使用。

📦 功能特性

✅ 多数据库支持 — 支持达梦8(DM8)、MySQL、PostgreSQL、Oracle、SQL Server、SQLite 等 14 种数据库
✅ 多源配置管理 — .env 统一管理全部数据库连接（多类型、多实例、多用户）
✅ LLM 智能 SQL 生成 — 集成 OpenAI 兼容 API，自然语言 → SQL 自动生成（支持 DeepSeek / 通义千问 / OpenAI 等）
✅ SQL 执行错误自动修正 — 执行报错时自动回传 LLM 修正 SQL
✅ 智能 Schema 获取 — 自动获取表名、字段名、数据类型及注释，组装为 LLM 友好的 Schema 描述
✅ SQL 安全校验 — 严格限制仅允许 SELECT / WITH 查询，拒绝 DDL/DML 危险操作
✅ 查询执行与导出 — 执行 SQL 并自动保存结果，支持导出为 Excel（.xlsx）
✅ 文件命名规范 — SQL 文件、结果文件、导出文件均按时间戳自动命名，整齐归档
✅ 连接测试工具 — 交互式或命令行模式，快速测试数据库连接，支持 --sql 自定义查询

🏗️ 项目结构

dm_ai_analyst/
├── main.py                       # 交互式 CLI 主入口（LLM 对话 + 查询执行）
├── query_runner.py               # 查询执行工具（SQL 执行 / 结果导出 / Dry-Run）
├── db_utils.py                   # 数据库工具模块（连接、Schema、SQL校验、执行、导出）
├── config.py                     # 配置解析与连接工厂（INI + .env 双源 / 14种驱动）
├── llm_utils.py                  # LLM 交互模块（SQL 生成 / 错误修正 / 连接测试）
├── prompts.py                    # 大模型提示词模板管理
├── test_conn.py                  # 数据库连接测试工具（交互 + CLI 模式）
├── pyproject.toml                # 项目元数据与版本管理
├── requirements.txt              # 依赖清单
├── AGENTS.md                      # 项目规范（代理指南：SQL 留痕、命名、Q/A）
├── GIT_RULES.md                  # Git/GitHub 提交规则
├── .python-version               # Python 版本锁（3.10）
├── .env.example                  # 环境变量模板（数据库连接 + API Key）
│
├── sql/                          # 最终确认的 SQL 文件（自动命名归档）
│   └── .gitkeep                  # 占位文件，确保目录被 Git 跟踪
│
├── export_dir/                   # 查询结果输出目录
│   ├── .gitkeep                  # 占位文件，确保目录被 Git 跟踪
│   ├── query_YYYYMMDD_HHMMSS.out  # 执行结果文本
│   └── 查询内容_YYYYMMDD_HHMMSS.xlsx  # Excel 导出文件
│
├── exec_py/
│   ├── run_count_tables.py       # 一次性任务：表记录数统计
│   └── .gitkeep
│
├── document/
│   ├── dm_ai_analyst架构设计.md  # 架构设计文档
│   ├── fx_plan.md                # 代码质量分析计划与修复记录
│   └── dm_ai_analyst_技术总结报告_v0.0.3.docx
│
└── .gitignore

⚙️ 快速开始

1. 安装依赖

# 方式一：使用 pyproject.toml（推荐）
pip install -e .

# 方式二：使用 requirements.txt
pip install -r requirements.txt

2. 安装数据库驱动（按需选择）

数据库	驱动	安装命令
达梦8	dmPython	`pip install dmPython`
MySQL	pymysql	`pip install pymysql`
PostgreSQL	psycopg2-binary	`pip install psycopg2-binary`
Oracle	cx_Oracle	`pip install cx_Oracle`
SQL Server	pymssql	`pip install pymssql`
SQLite	内置	无需安装

3. 配置数据库连接

复制 .env.example 为 .env，按需修改数据库连接参数：

项目使用 .env 统一管理所有数据库连接配置，命名规则为 DB_{类型}_{实例}_{属性}，代码自动扫描加载，无需手动枚举。支持 14 种数据库类型，多实例多用户。

cp .env.example .env

主要配置项：

# 默认连接（不指定 db_type/instance/user 时的回退值）
DM_HOST=127.0.0.1
DM_PORT=5236
DM_USER=SYSDBA
DM_PASSWORD=SYSDBA

# 多数据库/多实例/多用户扩展
# 命名规则：DB_{类型}_{实例}_{属性}
DB_DM8_LOCAL_HOST=127.0.0.1
DB_DM8_LOCAL_PORT=5236
DB_DM8_LOCAL_USERS=SYSDBA,USER1,USER2
DB_DM8_LOCAL_PASS_SYSDBA=Sysdba_123
DB_DM8_LOCAL_PASS_USER1=password1

⚠️ .env 包含数据库密码，已加入 .gitignore，不会提交到版本控制。 .env.example 则被正常跟踪，可以提交到 Git 仓库。

4. 配置 LLM API（可选）

将 .env.example 复制为 .env，填入大模型 API 参数：

cp .env.example .env

# LLM API 配置（兼容 OpenAI 格式）
LLM_API_KEY = sk-your-api-key
LLM_API_BASE = https://api.deepseek.com/v1    # 或 https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL = deepseek-chat                      # 或 qwen-turbo, gpt-4o 等
LLM_PROVIDER = openai

5. 测试 LLM 连接

python main.py --test-llm

6. 测试数据库连接

交互模式：

python test_conn.py

命令行模式：

python test_conn.py dm8 local SYSDBA
python test_conn.py dm8 local USER_ZWWW_BQGL --sql "SELECT 1 FROM DUAL" --show

7. 执行 SQL 查询

使用 query_runner.py（推荐）：

# 执行查询并保存 SQL + 结果文件
python query_runner.py dm8 local USER_ZWWW_BQGL "SELECT * FROM ZCZQ_POLICY_FILE"

# 执行查询并导出 Excel
python query_runner.py dm8 local USER_ZWWW_BQGL "SELECT * FROM ZCZQ_POLICY_FILE" --excel

# 安静模式（不打印结果到控制台）
python query_runner.py dm8 local USER_ZWWW_BQGL "SELECT * FROM ZCZQ_POLICY_FILE" --quiet

# 探索模式（仅输出，不保存文件）
python query_runner.py dm8 local USER_ZWWW_BQGL "SELECT COUNT(*) FROM ZCZQ_POLICY_FILE" --dry-run

8. 自然语言 → SQL（需配置 LLM API）

python main.py

进入交互式 CLI，输入自然语言即可自动生成 SQL 并执行。

🛠️ 核心模块说明

config.py — 配置与连接工厂

解析 .env 配置文件，管理多类型、多实例、多用户的数据库连接参数
内置驱动映射表，支持 14 种数据库类型
核心函数：create_connection(db_type, instance, user) 自动分发到正确的驱动连接
默认连接目标：dm8:local:USER_ZWWW_BQGL

db_utils.py — 数据库工具模块

功能	函数	说明
连接管理	`get_connection()` / `close_connection()`	单例模式管理数据库连接
Schema 获取	`get_all_tables()` / `get_table_columns()`	获取表名、字段名、数据类型、注释
Schema 缓存	`get_schema()` / `refresh_schema()`	带缓存的 Schema 获取，避免重复查询
Schema 描述	`build_schema_description()`	组装人类可读的 Schema 文本（供 LLM 使用）
SQL 校验	`validate_sql_safe()`	严格限制仅 SELECT / WITH 开头，拒绝危险操作
SQL 执行	`execute_sql()`	执行查询并返回 pandas DataFrame
Excel 导出	`export_to_excel()`	使用 pandas + openpyxl 导出 .xlsx

query_runner.py — 查询执行工具（推荐）

最终查询模式（默认）：自动保存 SQL 到 sql/、结果到 export_dir/，可选导出 Excel
探索模式（--dry-run）：仅输出到控制台，不保存任何文件

test_conn.py — 连接测试工具

交互式菜单选择数据库类型 → 实例 → 用户
支持 --sql 参数执行自定义查询预览
支持 --show 参数完整显示查询结果

llm_utils.py — LLM 交互模块

函数	说明
`generate_sql(user_question, schema_desc)`	自然语言 → SQL 自动生成
`fix_sql(sql, error_msg, schema_desc, original_question)`	SQL 执行错误自动修正
`test_llm_connection()`	测试 LLM API 连接是否正常

兼容 OpenAI API 格式，支持 DeepSeek / 通义千问 / OpenAI 等
自动清理 LLM 返回的 markdown 标记（```sql）

prompts.py — 提示词模板管理

SYSTEM_PROMPT — 系统级角色设定（达梦8 数据库专家）
build_sql_generation_prompt() — SQL 生成模板
build_sql_fix_prompt() — SQL 错误修正模板

📋 项目规范

项目规范 — 详见 AGENTS.md，核心规则：

文件类型	命名格式	存放位置
SQL 文件	`query_YYYYMMDD_HHMMSS.sql`	`sql/` 目录
结果文本	`query_YYYYMMDD_HHMMSS.out`	`export_dir/` 目录
导出 Excel	`查询内容_YYYYMMDD_HHMMSS.xlsx`	`export_dir/` 目录

探索性查询使用 --dry-run 参数，不允许保存中间文件
Git/GitHub 提交规则 — 详见 GIT_RULES.md，提交前务必阅读

🔌 支持的数据类型

配置键	实际数据库	底层驱动
`dm8`	达梦8	dmPython
`mysql`	MySQL	pymysql
`mariadb`	MariaDB	pymysql
`pgsql`	PostgreSQL	psycopg2
`oracle`	Oracle	cx_Oracle
`sqlserver`	SQL Server	pymssql
`sqlite`	SQLite	sqlite3（内置）
`kingbase`	人大金仓	psycopg2
`gaussdb`	GaussDB	psycopg2
`opengauss`	OpenGauss	psycopg2
`polardb`	PolarDB	pymysql
`oceanbase`	OceanBase	pymysql
`tidb`	TiDB	pymysql
`gbase`	GBase	pymysql

🧩 后续规划

集成 LLM API（DeepSeek / 通义千问 / OpenAI），实现自然语言 → SQL 自动生成
SQL 执行错误自动回传 LLM 修正
提供轻量级 Web 界面（如 Streamlit）
Schema 缓存持久化
Schema 缓存可视化（展示已缓存的表）
数据脱敏导出选项
多表关联关系在 Schema 描述中自动标注

📄 License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

dm_ai_analyst v0.0.3

📦 功能特性

🏗️ 项目结构

⚙️ 快速开始

1. 安装依赖

2. 安装数据库驱动（按需选择）

3. 配置数据库连接

4. 配置 LLM API（可选）

5. 测试 LLM 连接

6. 测试数据库连接

7. 执行 SQL 查询

8. 自然语言 → SQL（需配置 LLM API）

🛠️ 核心模块说明

config.py — 配置与连接工厂

db_utils.py — 数据库工具模块

query_runner.py — 查询执行工具（推荐）

test_conn.py — 连接测试工具

llm_utils.py — LLM 交互模块

prompts.py — 提示词模板管理

📋 项目规范

🔌 支持的数据类型

🧩 后续规划

📄 License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
exec_py		exec_py
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
AGENTS.md		AGENTS.md
GIT_RULES.md		GIT_RULES.md
README.md		README.md
config.py		config.py
db_utils.py		db_utils.py
llm_utils.py		llm_utils.py
main.py		main.py
prompts.py		prompts.py
pyproject.toml		pyproject.toml
query_runner.py		query_runner.py
requirements.txt		requirements.txt
test_conn.py		test_conn.py

Folders and files

Latest commit

History

Repository files navigation

dm_ai_analyst v0.0.3

📦 功能特性

🏗️ 项目结构

⚙️ 快速开始

1. 安装依赖

2. 安装数据库驱动（按需选择）

3. 配置数据库连接

4. 配置 LLM API（可选）

5. 测试 LLM 连接

6. 测试数据库连接

7. 执行 SQL 查询

8. 自然语言 → SQL（需配置 LLM API）

🛠️ 核心模块说明

config.py — 配置与连接工厂

db_utils.py — 数据库工具模块

query_runner.py — 查询执行工具（推荐）

test_conn.py — 连接测试工具

llm_utils.py — LLM 交互模块

prompts.py — 提示词模板管理

📋 项目规范

🔌 支持的数据类型

🧩 后续规划

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages