# magic-db-ai

**Repository Path**: liuyuecode/magic-db-ai

## Basic Information

- **Project Name**: magic-db-ai
- **Description**: MagicDB Studio 是一款 AI 驱动的跨平台数据库管理与 SQL 开发工具，旨在降低数据库使用门槛并提升 SQL 开发效率。

项目将传统数据库客户端与大语言模型能力结合，支持通过自然语言生成 SQL、解释和优化 SQL，并提供数据库连接管理、数据浏览、查询执行等常用功能。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Magic SQL AI

基于 Vue 3 + Spring Boot 的 AI 增强型数据库客户端，提供 SQL 编辑、AI 辅助、数据工具和专业运维能力。数据库支持按验证程度分为“内置并验证 / 驱动中心可扩展 / 目录展示与实验性”三档，不再用驱动目录数量代表完整可用能力。

## 功能特性

### 数据库连接
- **内置并验证** - E2E 默认启用 11 类：MySQL、PostgreSQL、MariaDB、ClickHouse、SQL Server、Oracle、TiDB、openGauss、SQLite、Redis、MongoDB Native
- **驱动中心可扩展** - `DbTypeEnum` 当前包含 37 个类型；驱动中心默认生成 34 个 JDBC 驱动模板，支持下载 Maven 驱动或上传自定义 JAR 后验证
- **目录展示 / 实验性** - DM8、KingBase、Oscar、HighGo 等测试配置保留为 Docker 待确认项；Kafka 与部分枚举类型属于专用能力或验证不足阶段
- **连接管理** - 创建/编辑/测试/删除，AES-256-GCM 密码加密
- **连接导入** - 支持多种数据库客户端导出的连接文件（.ncx / .json / .dbp）
- **高级连接** - SSH 隧道、SSL、云数据库预设（AWS RDS/阿里云/腾讯云/Azure）

### SQL 工作台
- **Monaco Editor** - 语法高亮、智能补全、SQL 格式化
- **多 Tab 编辑** - 最多 20 个 Tab，独立 SQL/连接/撤销栈
- **SQL 执行** - 当前/选中/全部执行，服务端分页，批量执行
- **数据编辑** - 单元格编辑 → UPDATE、新增行 → INSERT、删除行 → DELETE
- **虚拟主键** - 无主键表自动使用全列 WHERE + LIMIT 1 保护，支持配置持久化
- **结果视图** - Grid / Tree / JSON / 表单四种视图，支持 CSV/JSON/SQL/Excel/PDF 导出

### AI 助手
- **NL2SQL** - 自然语言转 SQL，SSE 流式输出
- **SQL 解释** - 解释 SQL 执行逻辑和优化建议
- **Schema 感知** - 自动附带当前连接表结构给 LLM
- **多 Provider** - 支持 OpenAI、通义千问、DeepSeek 等（YAML 可配置）

### 数据工具
- **数据同步** - 跨库表结构同步，生成同步脚本
- **数据对比** - 基于主键的行级差异比对，生成同步 DML
- **数据传输** - 跨库批量迁移，类型映射 + 进度跟踪
- **数据导入** - CSV/JSON/SQL 文件导入向导
- **数据生成器** - 按规则批量生成测试数据（12 种规则）
- **数据备份** - 全量/仅结构备份，GZIP 压缩

### 结构工具
- **结构对比** - 两个数据库的表结构差异对比
- **ER 图** - 数据库实体关系可视化与导出
- **ER 建模** - 可视化建模，逆向工程 + 正向工程（生成 DDL）
- **DDL 导出** - 单表/对象/全库 DDL 导出
- **数据字典** - 自动生成 HTML/Markdown 文档
- **表设计器** - 列定义、索引、外键、CHECK 约束、表选项

### 运维工具
- **服务器监控** - MySQL/PostgreSQL 状态、进程列表、慢查询、变量
- **可视化执行计划** - MySQL/PostgreSQL EXPLAIN JSON 解析
- **SQL 代码片段** - 分类管理 + 搜索 + 一键插入
- **批量 SQL 执行** - 多语句逐条执行，进度跟踪

### 安全与设置
- **SQL 安全守卫** - 可配置拦截 DROP/TRUNCATE/ALTER 等高危 SQL
- **只读模式** - 服务端可配置禁止 INSERT/UPDATE/DELETE
- **设置持久化** - 主题/字体/快捷键等设置后端持久化 + 导入导出

## 技术栈

### 后端
- Java 17
- Spring Boot 3.2.5
- MyBatis-Plus
- Druid 连接池
- H2 Database (元数据存储)
- Caffeine 缓存

### 前端
- Vue 3 + TypeScript
- Vite
- Element Plus
- Monaco Editor
- Pinia
- AG Grid

### 桌面端
- Electron + Vite
- 自动启动 Spring Boot 后端
- Windows / macOS / Linux 打包

## 快速开始

### 1. 启动后端

```bash
cd magic-sql-ai-server
mvn spring-boot:run
```

后端服务将在 http://localhost:18080 启动。

元数据持久化到 `magic-sql-ai-server/data/` 下的 H2 文件库。

### 2. 配置 AI（可选）

编辑 `magic-sql-ai-server/src/main/resources/application.yml`：

```yaml
ai:
  model:
    default-provider: default
    providers:
      default:
        base-url: https://api.openai.com
        completions-path: /v1/chat/completions
        model: gpt-4o-mini
        api-key: your-api-key
        temperature: 0.3
```

### 3. 启动前端

```bash
cd magic-sql-ai-client
npm install
npm run dev
```

前端服务将在 http://localhost:3000 启动，自动代理 `/api` 到后端。

### 4. 桌面端打包

```bash
cd magic-sql-ai-client
npm run electron:build
```

### 5. 测试入口

```powershell
# 一键运行后端单测、前端 Vitest、Python API 回归
.\scripts\test-all.ps1

# 仅运行 Python API 回归
python -m tests.run_all

# 前端单元测试 / E2E
cd magic-sql-ai-client
npm test
$env:MAGIC_LOCAL_PASSWORD = "1234"  # 若本地账号已有密码，E2E 需要设置
npm run test:e2e
```

## 项目结构

```
magic-db-ai/
├── magic-sql-ai-server/     # 后端 Spring Boot
│   ├── src/main/java/       # Java 源码
│   ├── src/main/resources/  # 配置 + schema
│   └── pom.xml
├── magic-sql-ai-client/     # 前端 Vue 3
│   ├── src/                 # 源码
│   ├── electron/            # Electron 主进程
│   └── package.json
├── docs/                    # 文档
└── README.md
```

## 核心 API

### 数据源
- `GET /api/datasource/list` - 数据源列表
- `POST /api/datasource` - 创建
- `PUT /api/datasource/{id}` - 更新
- `DELETE /api/datasource/{id}` - 删除
- `POST /api/datasource/{id}/test` - 测试连接

### SQL 执行
- `POST /api/sql/execute` - 执行 SQL
- `POST /api/sql/explain` - 执行计划

### 元数据
- `GET /api/metadata/databases` - 数据库列表
- `GET /api/metadata/tables` - 表列表
- `GET /api/metadata/table-detail` - 表详情
- `GET /api/metadata/ddl/table` - DDL 导出

### AI
- `POST /api/ai/generate-sql` - NL2SQL
- `POST /api/ai/explain-sql` - SQL 解释

## 版本历史

### v1.0.0 (2026-05-01)
- 首个正式发布版本
- 数据库支持按验证程度拆分为三档：默认验证集、驱动中心扩展模板、目录展示/实验性能力
- 完整的 SQL 工作台（编辑/执行/结果/导出）
- AI 助手（NL2SQL + SQL 解释）
- 数据工具（同步/对比/传输/导入/生成器/备份）
- 结构工具（结构对比/ER 图/ER 建模/DDL 导出/数据字典/表设计器）
- Electron 桌面端

## 许可证

MIT