数据库同步比对工具

一个 Windows 桌面应用（原生窗口 + 网页 UI），用于比对两个同类型数据库之间的表结构与表数据差异，并分别生成「让某一侧变成对方」的修复 SQL。应用只生成 SQL 供复制，绝不替你执行。

支持的数据库

类型	说明
Oracle（优先适配）	使用 python-oracledb 纯 Python 模式，无需安装 Oracle 客户端；支持服务名 / SID 两种方式
MySQL	通过 PyMySQL
SQLite	本机 .db 文件，方便无数据库环境时直接试用

两侧必须是相同类型的数据库（如：Oracle ↔ Oracle）。

启动方式

启动.bat

首次使用若提示缺少虚拟环境，先双击 初始化环境.bat。

开发目录中已建好 .venv，可直接双击 启动.bat。

环境要求

Windows 10/11（64 位）
Python 3.12（推荐）或 3.11 / 3.10
- ⚠️ 不要用 Python 3.13+：cffi / pythonnet 的预编译 wheel 在 3.13/3.14 上尚未就绪，会导致 pywebview 的 WinForms 后端 import _cffi_backend 失败，应用窗口起不来。
- 若本机已装 3.12，初始化环境.bat 会自动优先使用 %LOCALAPPDATA%\Programs\Python\Python312\python.exe。
- 没有 3.12 的话，脚本会 fallback 到 PATH 里的 python，但版本不满足 3.10–3.12 会报错退出。
首次初始化需要联网（pip 拉取 pywebview / oracledb / pymysql）。
WebView2 Runtime：Win10 2004+ / Win11 默认自带，无需额外安装。

常见启动问题排查

症状：双击启动.bat 后窗口没弹出来 / 一闪而过

多半是 venv 里的 Python 版本不对。验证方式：

.venv\Scripts\python.exe -c "import _cffi_backend; print('ok')"

如果报 ModuleNotFoundError: No module named '_cffi_backend'：venv 里的 Python 版本太新（3.13+），需要重建 venv：
1. 删除 .venv 目录
2. 重新双击 初始化环境.bat（会优先找 Python 3.12）
如果报 No module named 'webview'：你直接双击了 app.py，全局 Python 没装 pywebview。正确启动方式是双击 启动.bat，它会用 .venv 里的解释器。

症状：启动.bat 报 't' 不是内部或外部命令 或 ' ' 不是内部或外部命令

这是 .bat 文件编码问题。本仓库的 .bat 文件必须保持纯 ASCII（提示信息用英文，不写中文），因为 Windows 中文系统的 cmd 按 GBK 解析批处理文件，UTF-8 中文会被拆成乱码字节变成不存在的命令。如果被编辑器改成 UTF-8，需要改回 ASCII 或用 ANSI 保存。

使用流程

连接两侧数据库：左右两栏各填一份连接信息。保存时配置名以及当前数据库类型所需的连接字段不能为空；「仅保存」不访问数据库，适合数据库暂时不可用时先保存配置；「保存并连接」会先保存，再尝试连接，失败时保留表单内容和原有连接。配置保存在 %USERPROFILE%\.dbsync_tool\connections.json（密码仅做 Base64 混淆，请自行保管好机器）。
切换连接：已连接后，每栏顶部的下拉框可快速切换到其他已保存的连接；选择「＋新建数据库链接」回到连接表单。连接弹窗只通过「取消」按钮关闭，点击背景蒙板不会丢失已填写内容。
对比表（结构比对）：在顶部共享查询栏左侧点「对比表」，输入一个或多个表名（逗号/换行分隔），点「开始比对结构」：
- 顶部共享查询栏可打开表名下拉搜索并多选，列表会标出表存在于两侧还是仅存在于一侧；
- 成功比对后会在本机持久化存储最近 20 条对比表历史，关闭应用再次启动后仍会保留；下拉中最多显示约 5 条高度并可滚动，可快速回填、删除单条或清空全部历史；
- 中部显示每张表的差异明细（缺列/多列/类型/可空/默认值/主键差异）；
- 左下 SQL = 在左侧库执行后结构与右侧一致；右下 SQL 反之。点「复制SQL」即可。
对比数据（数据比对）：在顶部共享查询栏左侧点「对比数据」，选择/输入一张表，点「开始比对数据」：
- 成功比对后会持久化存储最近 20 条“表名 + WHERE”历史，可在正常表列表底部快速回填、删除单条或清空全部历史；
- 顶部共享查询栏中的表名使用浅色可搜索下拉，两侧都存在的表可直接选择；
- 可选填写共享 WHERE 过滤条件（可省略 WHERE 前缀）；
- WHERE 执行失败时会明确提示出错的是左侧还是右侧数据库；
- WHERE 范围内任一侧超过 500 行时会先提示，可返回缩小范围或确认继续；
- 按主键比对行（无主键时只能识别多/少行）；
- 差异不超过 2000 条时展示全部明细；超过时仅展示前 200 条；
- 两侧各自输出行级修复 SQL（INSERT/UPDATE/DELETE），仅供复制；单方向超过 5000 条时会截断并要求使用 WHERE 分批处理。

给 AI agent 使用的 MCP 服务

仓库同时提供一个与桌面窗口完全解耦的只读 MCP 服务：mcp/server.py，以及一个用于配置 agent 的图形界面 mcp/configurator.py。它只读取本工具已经保存的 %USERPROFILE%\.dbsync_tool\connections.json，不能通过 MCP 新增或修改数据源；密码只在服务进程内用于连接， list_data_sources 以及所有工具结果都不会返回密码。

先在桌面工具中保存并测试数据源，再把下面的命令配置到支持 stdio MCP 的 AI agent。服务由 agent 自动启动和管理，不需要用户手工运行。MCP 初始化响应会告诉 agent 先调用 list_data_sources，再按数据源名称找到 source_id，因此用户可以直接说“查询 XXX 数据源的 EMP 表结构”。

{
  "mcpServers": {
    "dbsync": {
      "command": "D:\\AllCode\\py\\db-diff-sync-tool\\.venv\\Scripts\\python.exe",
      "args": ["D:\\AllCode\\py\\db-diff-sync-tool\\mcp\\server.py"]
    }
  }
}

提供的工具为：list_data_sources、list_tables、list_views、get_table_schema、 get_view_schema、read_table 和 read_view。读取表/视图数据可传 where，单次 limit 最大为 500（缺省也是 500）；表名、视图名和 WHERE 条件沿用应用的标识符及分号/注释拦截规则。服务只执行 SELECT 和元数据查询，不会执行任何修复 SQL。

配置界面可以通过双击 mcp/配置中心.bat 打开，也可以运行：

.venv\Scripts\python.exe mcp\configurator.py

界面会扫描 Codex、Claude Code、OpenCode 是否已安装，并显示全局安装和当前项目安装状态。全局安装会让所有项目可用；项目安装需要先选择项目目录。安装前会读取目标 agent 的真实配置，已经存在 dbsync 时只提示已安装，不会重复写入。

界面展示

下面是旧界面的截图

目录结构

app.py            应用入口与 JS API 桥（连接管理、比对调度）
mcp/              面向 AI agent 的只读 MCP stdio 服务（入口为 server.py）
package_windows.py Unicode-safe Windows PyInstaller 打包入口
dbcore.py         比对核心：三种方言的元数据读取、结构/数据差异 SQL 生成
web/              网页 UI 与应用图标（app-icon.svg / app-icon.png / app-icon.ico）
tests/selftest.py 自测：SQLite 双库端到端验证 + Oracle/MySQL SQL 文本校验
启动.bat          启动应用
mcp/配置中心.bat  打开 MCP 配置中心
初始化环境.bat     首次创建虚拟环境
打包.bat          打包 exe，并在存在 Instant Client 时自动带上 Oracle 11g thick mode 依赖
清空用户数据.bat   删除本机当前 Windows 用户下保存的连接配置、会话状态、历史记录和 WebView 缓存

清空本机用户数据

源码启动版、本地打包版和 GitHub 下载版会共用当前 Windows 用户下的数据目录：

%USERPROFILE%\.dbsync_tool\

如果不再使用本工具，或想彻底清空本机保存的连接配置、会话状态、比对历史和 WebView 缓存，可以双击：

清空用户数据.bat

脚本会要求输入 DELETE 二次确认后才删除；删除后不可恢复。

自测

.venv\Scripts\python.exe tests\selftest.py
.venv\Scripts\python.exe tests\test_where.py
.venv\Scripts\python.exe tests\test_limits.py
.venv\Scripts\python.exe tests\test_urls.py
.venv\Scripts\python.exe tests\test_profiles.py
.venv\Scripts\python.exe tests\test_mcp_server.py
.venv\Scripts\python.exe tests\test_mcp_configurator.py

连接弹窗的“粘贴 JDBC URL / DSN”支持 Oracle SID/服务名，以及带账号密码的 jdbc:oracle:thin:user/password@host:1521:SID；MySQL 支持 mysql://... 和 jdbc:mysql://host:3306/database?...，末尾的 JDBC 连接参数会自动忽略。

限制说明

数据比对为全量内存比对，单表上限 20 万行；单方向输出 SQL 上限 5000 条（超出截断并注明）。
结构比对覆盖：列（类型/可空/默认值/备注）、主键、表备注和索引；Oracle 整表缺失时还会还原命名主键、唯一约束及其关联索引。暂不含外键、触发器、视图。
修改列定义/主键时，SQLite 会生成重建表方案；Oracle/MySQL 用 ALTER。
DROP 类语句前都有警告注释，请在数据库工具里确认后再执行。

打包成 exe（可选）

推荐直接双击：

打包.bat

产物在 dist\数据库同步比对工具\。打包.bat 只负责调用 ASCII 安全的入口，package_windows.py 使用 ASCII 内部构建名生成 PyInstaller 产物，再将最终目录和 exe 改为中文名称，并将 web\app-icon.ico 同时用于 exe、窗口和任务栏图标。产物中的 mcp\ 子目录还包含 dbsync-mcp.exe（stdio 服务）和 dbsync-mcp-configurator.exe（配置界面）。

Oracle 11g 依赖打包

连接 Oracle 11.2 时需要 python-oracledb 的 thick mode。Oracle Instant Client 19c 是 Oracle 官方支持连接 Oracle 11.2 及更高版本的客户端组合。打包脚本会自动检查并打包 .oracle_client 下任一包含 oci.dll 的 instantclient_* 目录，例如：

.oracle_client\instantclient_19_31\oci.dll

使用方式：

下载并解压与目标数据库兼容的 Oracle Instant Client for Windows x64（Basic 或 Basic Light）。
在项目根目录新建 .oracle_client\instantclient_19_31\（目录名也可为其他 instantclient_*）。
将解压后的 oci.dll、oraociei*.dll / oraociicus*.dll、oraons.dll、network\admin（如有 tnsnames.ora）等文件放入该目录。
运行 打包.bat。脚本会把该目录打进 exe 产物，运行时会优先从打包目录初始化 Oracle thick mode。

如果没有放置 Instant Client，打包仍会继续，程序运行和连接较新的 Oracle 都不会因为缺少 oci.dll 报错；此时会使用 python-oracledb 默认 thin mode。

GitHub Actions 会在每次推送时运行测试。只有推送到 main 分支或推送 tag 时，才会打包并发布 Windows x64 ZIP：

db-sync-tool-windows-x64-thin-*.zip：未携带 Instant Client，适合 Oracle 12.1+、MySQL 和 SQLite。
db-sync-tool-windows-x64-oracle11g-*.zip：内置 Oracle Instant Client 19c，适合 Oracle 11.2+、MySQL 和 SQLite。

如果 Oracle 官方下载链接临时不可用或校验失败，GitHub Actions 会跳过 Oracle 11g 包，但仍继续发布 thin 包。 Actions artifact 只保留 3 天；main 分支产生的 auto-v* / 旧 build-* 自动预发布只保留最近 10 个，tag 发布不会被自动清理。自动发布会先删除同名旧 release 再重建，确保最新一版排在 Release list 前面。标题、tag 和 ZIP 文件名会使用 app.py 中的版本号。

依赖版本参考（venv Python 3.12 实测通过）

GitHub Actions 和 初始化环境.bat 使用 requirements.txt 锁定下面的版本，避免 pywebview / pythonnet / clr_loader / PyInstaller 自动升级后打包产物启动失败。

依赖	版本	说明
pywebview	6.2.1	窗口容器（WinForms 后端）
pythonnet	3.1.0	pywebview 在 Windows 上的 .NET 绑定
cffi	2.1.0	pythonnet 的底层 C FFI，必须有预编译 wheel（Python 3.12 有，3.13+ 目前没有）
oracledb	4.0.2	Oracle 驱动，纯 Python 模式，免 Oracle 客户端
PyMySQL	1.2.0	MySQL 驱动

变更日志

2026-08-09（v2.0.20）：修复打包版 MCP 配置中心页面资源路径错误导致的 404，以及 JS API 循环引用导致的窗口未响应。
2026-08-09（v2.0.19）：修复从 GitHub ZIP 解压后 MCP 配置中心因 Windows Internet Zone 标记导致的 pywebview/pythonnet 启动失败。
2026-08-07（v2.0.18）：MCP 配置中心改为无 CMD 依赖启动，初始页面先选择项目，再检查 agent，修复启动阻塞和窗口交互问题。
2026-08-07（v2.0.17）：修复 MCP 配置中心启动时扫描阻塞和 CMD 依赖，改为选择项目后再检查 agent。
2026-08-07（v2.0.16）：新增 MCP 配置中心界面，可扫描 Codex、Claude Code、OpenCode 并执行全局或项目安装。
2026-08-07（v2.0.15）：在 MCP 初始化响应中加入服务使用说明和只读工具标注，方便 agent 自动理解调用流程。
2026-08-07（v2.0.14）：将 MCP 服务归档到独立的 mcp/ 目录，移除容易造成手工启动误解的批处理入口。
2026-08-07（v2.0.13）：新增与桌面窗口解耦的只读 MCP 服务，支持数据源、表/视图结构和最多 500 行数据读取。
2026-08-04（v2.0.12）：main 自动发布改为先删除同名旧 release 再重建，避免同版本更新后仍停留在 Release list 中间。
2026-08-04（v2.0.11）：GitHub Actions 发布标题、自动 tag、artifact 名称和 ZIP 文件名改为使用应用版本号，减少 release 页面中的长提交哈希。
2026-08-04（v2.0.10）：新增 清空用户数据.bat，用于彻底删除当前 Windows 用户下的 .dbsync_tool 本机数据；本地打包脚本改为使用 requirements.txt 锁定依赖。
2026-08-04（v2.0.9）：新增 requirements.txt 并让 GitHub Actions、初始化脚本使用锁定依赖；打包程序启动时会尝试移除 DLL/EXE 的 Windows Internet Zone 标记，避免 GitHub 下载包解压后 pythonnet 启动时报 Python.Runtime.Loader.Initialize 解析失败。
2026-08-04（v2.0.7）：GitHub Actions 改为普通分支只跑测试，main 和 tag 才打包发布；artifact 保留 3 天，并自动清理仅保留最近 10 个 build-* 自动预发布。
2026-08-04（v2.0.6）：GitHub Actions 在 Oracle Instant Client 下载失败时改为跳过 Oracle 11g 包，继续发布 thin 包，避免外部下载源影响普通版本发布。
2026-08-04（v2.0.5）：GitHub Actions 同时发布 Oracle thin mode 和内置 Instant Client 19c 的 Oracle 11g（11.2+）兼容包；本地打包与运行时自动识别 .oracle_client\instantclient_*。
2026-08-04（v2.0.4）：启动前清理 WebView 网页资源缓存并保留 Local Storage，修复窗口标题已更新但结构比对页面仍执行旧脚本、单侧颜色不生效的问题。
2026-08-04（v2.0.3）：修复 Oracle 列默认值中的 SQL 注释导致生成的 ALTER TABLE ... MODIFY 右括号被注释的问题；结构比对明细改为由后端明确标记单侧归属，本侧存在显示浅蓝色，本侧缺失显示浅红色。
2026-07-31：修复 Python 3.14 下 venv 无法启动的问题（cffi 缺失预编译 wheel → pythonnet → pywebview WinForms 后端整条链断掉）。初始化环境.bat 改为优先用本机 Python 3.12 绝对路径重建 venv；README 新增环境要求与常见启动问题排查章节。

Navigation Menu

Repository files navigation

数据库同步比对工具

支持的数据库

启动方式

环境要求

常见启动问题排查

使用流程

给 AI agent 使用的 MCP 服务

界面展示

目录结构

清空本机用户数据

自测

限制说明

打包成 exe（可选）

Oracle 11g 依赖打包

依赖版本参考（venv Python 3.12 实测通过）

变更日志

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.codegraph		.codegraph
.github/workflows		.github/workflows
.idea		.idea
.img		.img
.oracle_client		.oracle_client
mcp		mcp
tests		tests
web		web
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
app.py		app.py
dbcore.py		dbcore.py
package_windows.py		package_windows.py
requirements.txt		requirements.txt
初始化环境.bat		初始化环境.bat
启动.bat		启动.bat
打包.bat		打包.bat
清空用户数据.bat		清空用户数据.bat

Folders and files

Latest commit

History

Repository files navigation

数据库同步比对工具

支持的数据库

启动方式

环境要求

常见启动问题排查

使用流程

给 AI agent 使用的 MCP 服务

界面展示

目录结构

清空本机用户数据

自测

限制说明

打包成 exe（可选）

Oracle 11g 依赖打包

依赖版本参考（venv Python 3.12 实测通过）

变更日志

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages