# springoot-sql-compare

**Repository Path**: wang_zhu_ge/springoot-sql-compare

## Basic Information

- **Project Name**: springoot-sql-compare
- **Description**: 开发一个本地轻量工具，用于对比两个 MySQL 数据库的表结构，并生成可下载的修复 SQL 文件。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MySQL Schema Compare

一个基于 Spring Boot 的本地 MySQL 表结构对比工具。它以一个数据库作为标准库，生成或导入标准结构快照，再与目标库进行结构对比，并输出可下载的修复 SQL 文件。

本工具只负责发现结构差异并生成 SQL，不会自动连接目标库执行任何变更语句。

## 系统页面

![img.png](image/img.png)

## 功能特性

- 维护两套固定 MySQL 连接配置：标准库 `baseline` 和目标库 `target`
- 支持连接测试，测试过程不扫描表结构
- 支持从标准库生成结构快照
- 支持导入和下载标准结构 JSON
- 使用本地 SQLite 持久化连接配置、标准结构和排除规则
- 支持表排除规则：精确匹配、前缀匹配、后缀匹配、包含匹配
- 对比目标库后生成 SQL 文件下载
- 对长耗时任务提供异步任务状态和进度轮询
- 临时 SQL 文件自动清理，默认保留 60 分钟
- 提供原生 HTML/CSS/JavaScript 前端页面，无需单独构建前端

## 对比范围

当前支持：

- 缺失表：生成 `CREATE TABLE`
- 缺失字段：生成 `ALTER TABLE ... ADD COLUMN`
- 字段定义差异：生成 `ALTER TABLE ... MODIFY COLUMN`
- 多余表和多余字段：只在结果中统计或写入注释，不生成删除语句

当前不处理：

- 删除表、删除字段
- 索引差异
- 表引擎差异
- 表字符集和排序规则差异
- 字段字符集和排序规则差异
- 自动执行 SQL
- 多标准快照和对比历史

## 技术栈

- Java 8
- Spring Boot 2.7.18
- Spring MVC
- Spring JDBC
- MySQL Connector/J
- SQLite JDBC
- Lombok
- 原生 HTML/CSS/JavaScript

## 快速开始

### 环境要求

- JDK 8+
- Maven 3.6+，或直接使用项目内置的 Maven Wrapper
- 可访问的 MySQL 实例

### 启动应用

```bash
./mvnw spring-boot:run
```

默认监听地址：

```text
http://localhost:18080
```

应用启动后会自动创建本地数据目录和 SQLite 文件：

```text
data/schema-compare.sqlite
data/tmp-sql/
```

这些运行期数据已加入 `.gitignore`，不应提交到代码仓库。

## 使用流程

1. 打开 `http://localhost:18080`
2. 填写标准库和目标库连接信息
3. 分别点击“测试连接”确认配置可用
4. 点击“生成标准结构”，或导入已有标准 JSON
5. 按需配置表排除规则
6. 点击“开始对比”
7. 对比完成后下载生成的 SQL 文件
8. 人工审核 SQL 后，再自行决定是否在目标库执行

## 配置项

配置文件位于：

```text
src/main/resources/application.yaml
```

主要配置：

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `server.address` | `0.0.0.0` | 服务监听地址 |
| `server.port` | `18080` | 服务端口 |
| `schema-compare.sqlite-path` | `./data/schema-compare.sqlite` | SQLite 数据文件路径 |
| `schema-compare.sql-temp-dir` | `./data/tmp-sql` | 临时 SQL 文件目录 |
| `schema-compare.sql-file-retention-minutes` | `60` | 临时 SQL 文件保留时间 |
| `schema-compare.mysql-connect-timeout-seconds` | `5` | MySQL 连接超时 |
| `schema-compare.mysql-query-timeout-seconds` | `300` | MySQL 元数据查询超时 |
| `schema-compare.mysql-show-create-timeout-seconds` | `30` | `SHOW CREATE TABLE` 查询超时 |

## 本地数据

SQLite 会保存以下信息：

- 标准库和目标库连接配置
- 数据库密码，当前为明文存储
- 当前唯一一份标准结构快照
- 表排除规则

SQLite 表结构由应用启动时自动初始化，核心表包括：

- `db_config`
- `schema_snapshot`
- `app_setting`

### 表结构设计

`db_config` 保存固定的两套数据库连接配置。

```sql
CREATE TABLE IF NOT EXISTS db_config (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  role TEXT NOT NULL UNIQUE,
  host TEXT NOT NULL,
  port INTEGER NOT NULL,
  database_name TEXT NOT NULL,
  username TEXT NOT NULL,
  password TEXT NOT NULL,
  updated_at TEXT NOT NULL
);
```

| 字段 | 说明 |
| --- | --- |
| `id` | 自增主键 |
| `role` | 连接角色，固定为 `baseline` 或 `target` |
| `host` | MySQL 主机地址 |
| `port` | MySQL 端口 |
| `database_name` | 数据库名 |
| `username` | 用户名 |
| `password` | 明文密码 |
| `updated_at` | 更新时间 |

`schema_snapshot` 保存当前唯一一份标准结构快照。

```sql
CREATE TABLE IF NOT EXISTS schema_snapshot (
  id INTEGER PRIMARY KEY CHECK (id = 1),
  database_name TEXT NOT NULL,
  generated_at TEXT NOT NULL,
  table_count INTEGER NOT NULL,
  column_count INTEGER NOT NULL,
  content_json TEXT NOT NULL
);
```

| 字段 | 说明 |
| --- | --- |
| `id` | 固定为 `1`，保证只保存一份标准结构 |
| `database_name` | 标准结构来源库名 |
| `generated_at` | 生成或导入时间 |
| `table_count` | 表数量 |
| `column_count` | 字段数量 |
| `content_json` | 完整标准结构 JSON |

`app_setting` 保存排除规则等简单配置。

```sql
CREATE TABLE IF NOT EXISTS app_setting (
  key TEXT PRIMARY KEY,
  value TEXT NOT NULL
);
```

| 字段 | 说明 |
| --- | --- |
| `key` | 配置键 |
| `value` | 配置值，排除规则以 JSON 字符串保存 |

## 安全说明

该工具定位为本地或可信内网临时工具，不包含登录鉴权。

需要特别注意：

- 服务默认监听 `0.0.0.0`，同一网络内的其他机器可能访问
- 数据库密码会以明文写入本地 SQLite，并在接口中明文返回给前端
- 下载的 SQL 需要人工审核后再执行
- 建议只在可信网络中运行，用完后关闭服务

如需限制为本机访问，可将配置改为：

```yaml
server:
  address: 127.0.0.1
```

## 项目结构

```text
.
├── src/main/java/com/adx
│   ├── SpringBootSqlCompareApplication.java
│   └── schema
│       ├── config        # SQLite、异步任务和配置初始化
│       ├── controller    # REST API
│       ├── model         # 请求、响应和领域模型
│       ├── repository    # SQLite 数据访问
│       ├── service       # 核心业务逻辑
│       ├── task          # 异步任务状态管理
│       └── util          # SQL、标识符和排除规则工具
├── src/main/resources
│   ├── application.yaml
│   └── static            # 前端页面
├── src/test/java         # 单元测试
├── docs                  # 开发文档
└── data                  # 本地运行期数据，不提交
```

## 测试

运行全部测试：

```bash
./mvnw test
```

## 构建

```bash
./mvnw clean package
```

构建产物位于：

```text
target/
```

运行打包后的应用：

```bash
java -jar target/springboot-sql-compare-0.0.1-SNAPSHOT.jar
```