# sql-rag-coder

**Repository Path**: felix870303/sql-rag-coder

## Basic Information

- **Project Name**: sql-rag-coder
- **Description**: 基板上传
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SQL RAG Coder

面向 SQL、清算任务、监控接口和报表过程生成的 RAG 辅助开发工具。

## 核心能力

1. 读取 `data/sql` 下的整库表结构、清算表、接口配置、清算任务、存储过程。
2. 建立 Chroma 向量索引和结构化表字段索引。
3. 根据需求调用 DeepSeek 生成接口配置、清算任务、DDL、报表 SQL 或存储过程。
4. 支持多人按 `user_id` 保存各自草稿。
5. 支持手工选择是否把编辑后的 SQL 保存到 `data/sql/user_generated` 并重建索引。
6. 支持把编辑后的 SQL 通过 JDBC 发送到数据库执行并查看结果。

## Setup

```powershell
cd G:\pyPro\sql-rag-coder
G:\Python\Python311\python.exe -m venv .venv
.\.venv\Scripts\activate
python -m pip install -r requirements.txt
copy .env.example .env
```

编辑 `.env`：

```text
DEEPSEEK_API_KEY=your_key_here
```

## Run

```powershell
uvicorn app.main:app --host 172.16.102.176 --port 8000
```

打开：

```text
http://172.16.102.176:8000
```

## 多人草稿和索引

- 页面左侧填写“使用人标识”，例如 `zhangsan`。
- 点击“保存当前编辑内容”后，默认保存到 `storage/workspaces/<user_id>`，不会影响项目索引。
- 勾选“保存到项目 SQL 索引并重建索引”后，会复制到 `data/sql/user_generated/<user_id>` 并自动重建索引。

## JDBC 执行

数据库执行使用 `jaydebeapi + JPype1` 调用 JDBC 驱动。项目不内置各厂商 jar，需要你在页面填写：

- JDBC URL
- Driver Class
- Driver Jar 路径
- 用户名/密码

常见 Driver Class：

```text
MySQL/TDSQL: com.mysql.cj.jdbc.Driver
Oracle: oracle.jdbc.OracleDriver
SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver
达梦: dm.jdbc.driver.DmDriver
高斯: org.postgresql.Driver
人大金仓: com.kingbase8.Driver
```

注意：DDL/DML 会提交事务，生成 SQL 必须人工确认后再执行。
## 数据库执行器抽象

后端已经抽象为统一 `DatabaseExecutor`，目前内置两种实现：

```text
JdbcExecutor        通过 jaydebeapi + JPype1 调用 JDBC，适合国产库和 JDBC 覆盖优先场景。
SqlAlchemyExecutor 通过 SQLAlchemy URL 调用 Python 原生驱动，适合 MySQL、Oracle、SQL Server、PostgreSQL 等主流库。
```

页面“执行方式”可选择 JDBC 或 SQLAlchemy。

SQLAlchemy URL 示例：

```text
mysql+pymysql://user:password@127.0.0.1:3306/dbname
oracle+oracledb://user:password@host:1521/?service_name=orclpdb
mssql+pyodbc://user:password@dsn_name
postgresql+psycopg://user:password@127.0.0.1:5432/dbname
```

SQLAlchemy 方式需要额外安装对应 Python 驱动，例如：

```powershell
python -m pip install pymysql oracledb pyodbc psycopg
```

## 流式生成

页面新增“流式调用 DS”按钮，后端接口为 `/api/generate-stream`，使用 Server-Sent Events 逐段返回模型内容，前端会把结果叠加输出到可编辑结果区。
## 项目内 JDBC 驱动

JDBC 驱动统一放到项目根目录 `drivers` 下。页面会自动调用 `/api/drivers` 读取 jar 列表，并根据数据库类型推荐 Driver Class 和 jar。

例如 MySQL 可以直接使用：

```text
Driver Class: com.mysql.cj.jdbc.Driver
Driver Jar: drivers/mysql-connector-java-8.0.18.jar
```

也可以手工填写绝对路径；项目相对路径和绝对路径都支持。

## SQL 自动识别与执行

DeepSeek 返回结果中往往包含分析说明、配置说明和多段 SQL。页面不会再要求把整段内容复制到执行框，而是会自动识别：

- Markdown fenced code block，例如 ` ```sql `
- 正文中明显以 SELECT、INSERT、CREATE、ALTER、CALL 等开头的 SQL 片段

识别出的每个 SQL 片段都会显示为独立卡片，并提供：

- 载入待执行
- 执行此 SQL
## 数据库配置保存

页面中的数据库配置采用弹窗管理。测试连接成功后，可以填写配置名称并保存到服务端，下次直接选择使用。

配置文件位置：

```text
storage/db_profiles.json
```

当前开发版本会把密码保存到本地 JSON。正式多人部署时建议改成加密保存或接入专门的凭据管理服务。

## 草稿/索引可视化编辑

页面“草稿/索引”Tab 支持：

- 按用户列出 `storage/workspaces` 下的草稿
- 可选列出 `data/sql/user_generated` 下已纳入索引的 SQL
- 点击文件后读取内容
- 在页面编辑并覆盖保存
- 可选择保存后重建索引
## 索引源管理

“索引源”指 `data/sql` 下真正参与 RAG 检索的 SQL 文件。开发过程中如果出现未导入的新表、字段变化、过程变化，可以在页面“索引源”Tab 中新增或编辑对应 SQL 文件，并选择保存后重建索引。

新增文件默认建议放到：

```text
data/sql/user_added/<category>/<object_name>.sql
```

## 最终提示词编辑

左侧“需求描述”不是最终发给 DeepSeek 的内容。后端会把需求、数据库方言、任务类型、草稿内容和检索上下文组装成 OpenAI/DeepSeek chat messages。

页面“最终提示词”Tab 支持：

- 预览真实发送给 DeepSeek 的 System Prompt 和 User Prompt
- 手工修改提示词
- 使用修改后的提示词普通调用 DeepSeek
- 使用修改后的提示词流式调用 DeepSeek

## 检索策略链、检索信息与 DS 调用关系

“索引关系”页用于调试和配置本次需求的检索策略链。调整策略步骤、排除分类、TopK 或匹配方式后，需要点击“同步普通检索”，当前策略链的命中结果才会同步为普通检索上下文。

同步后的上下文会影响后续本次 DS 调用，包括：

- “最终提示词”Tab 中的真实 System Prompt / User Prompt 生成
- “普通调用 DS”
- “流式调用 DS”

“检索信息”Tab 是调用 DS 前最后一层人工确认入口。这里展示的是即将写入 User Prompt 的候选上下文，可以通过勾选或取消勾选来决定哪些命中片段参与本次提示词生成。

推荐操作顺序：

1. 在“索引关系”中调整检索策略链。
2. 点击“执行策略链”，查看每一步命中情况。
3. 点击“同步普通检索”，把当前策略链结果同步为普通检索上下文。
4. 切换到“检索信息”，人工确认或裁剪候选上下文。
5. 切换到“最终提示词”，点击“重新生成真实提示词”。
6. 检查或二次编辑提示词后，再调用 DS。

注意：“检索信息”不是事后展示，而是本次调用前对上下文的最后一次干预位置。如果这里取消勾选某些片段，重新生成提示词后，这些片段不会进入本次 DS 调用。