README

问题

我发现了一些可靠的迁移工具，例如 Flyway 和 Simple DB Migrate，后者因其简洁性是我的首选，但前者有更多的提交和贡献者。然而，这些只是迁移器，并不能帮助产生实际要版本化的diff/migration，如果可以自动化的话，我不愿意手动完成。

我发现了一个MySQL的diff工具，名为 mysqldbcompare，它输出用于（一些）模式和数据变化的SQL，但它出人意料地没有产生有效的SQL！！！

不过，mysqldbcompare工具提供的所有功能都非常出色，它通过直接连接源数据库和目标数据库（可以是本地或另一台服务器）来执行一系列测试/检查（所有这些都可以根据需要跳过），然后检查模式和数据——但我们只需要它能产生有效的SQL输出，我认为它也难以完全验证模式。

实际上，我查阅了许多不同的模式和数据diff工具（花了我整整一个周末）并且它们要么

1. 只做模式diff
2. 过于复杂而难以工作
3. 无法产生有效的SQL

解决方案

我认为一个可靠的迁移工具与一个自动化的模式和数据diff工具的结合对开源社区将是一个很大的贡献。

这就是DBDiff的目的。

DBDiff的功能

• 在Windows、Linux & Mac的命令行/Terminal上运行，因为它是用PHP开发的
• 连接到源数据库和目标数据库以进行比较diff，本地和远程均可
• diff可以包括模式和/或数据的更改，都将以有效的SQL形式提供，以便将目标数据库更新到与源数据库一致
• 可以通过配置文件中的YAML集合忽略某些表和/或字段进行比较（请参阅下面的文件示例）
• diff非常快，并且已经测试过具有数百万行表的大型数据库
• 由于这个diff工具用于迁移，因此它在同一个文件中提供上和下的SQL
• 可以通过指定输出模板文件/格式与现有的迁移工具（如Flyway和Simple DB Migrate）一起工作，例如，Simple DB Migrate可能使用simple-db-migrate.tmpl工作，该模板包括： SQL_UP = u""" {{ $up }} """ SQL_DOWN = u""" {{ $down }} """
• 支持Unicode，可以处理UTF8数据，包括外文字符/符号
• 目前仅支持MySQL，但我们将根据需求扩展到其他数据库（请创建一个问题！）

先决条件

1. 您需要访问命令行，对于Linux/Mac，是一个终端，对于Windows，将是命令提示符（cmd）
2. 您需要安装git： https://git-scm.cn/downloads
3. 您需要安装PHP（版本5.4.x）： https://php.ac.cn/manual/en/install.php
4. 您需要安装Composer，这是一个PHP的依赖管理器： https://composer.php.ac.cn

注意：注意composer.phar的安装位置，我们将在设置过程中需要它

安装

在命令行中，使用 git 克隆 SSH 版本

git clone git@github.com:Thomasbehan/DBDiff.git

或者 使用 git 克隆 HTTPS 版本

git clone https://github.com/Thomasbehan/DBDiff.git

或者 下载 .zip 归档并将其解压到您选择的文件夹中，例如 dbdiff

https://github.com/Thomasbehan/DBDiff/archive/master.zip

或者 使用 composer 将 DBDiff 作为项目依赖项包含

php composer.phar require "Thomasbehan/DBDiff:@dev"

设置

确保您处于应用程序的根目录，并使用 'cd' 命令在命令行中导航到您放置 "dbdiff" 文件夹的位置

我们假设 composer.phar 已安装在内置的 "dbdiff" 文件夹中。如果它安装在其他位置，您将需要使用它的确切路径

1. 如果您没有使用 composer 安装 DBDiff，请使用以下命令安装项目的依赖项：php composer.phar install
2. 按照 文件示例 制作一个 .dbdiff 文件，并将其放置在 "dbdiff" 目录的根目录下
3. 输入 ./dbdiff {dbdiff 命令，例如 server1.db1:server1.db2} 以启动应用程序！请参阅 命令行 API 了解有关可以运行的命令的更多信息。

您应该看到类似...

ℹ Now calculating schema diff for table `foo`
ℹ Now calculating data diff for table `foo`
ℹ Now generating UP migration
ℹ Now generating DOWN migration
ℹ Writing migration file to /path/to/dbdiff/migration.sql
✔ Completed

恭喜您已成功安装并运行了 DBDiff！

命令行 API

注意：命令行参数将始终覆盖 .dbdiff 配置文件中的设置

• --server1=user:password@host1:port - 指定源数据库连接详细信息。如果只有一个服务器，则可以省略 --server1 标志
• --server2=user:password@host2:port - 指定目标数据库连接详细信息（如果与 server1 不同）
• --template=templates/simple-db-migrate.tmpl - 指定输出模板（如果有）。默认将使用纯 SQL
• --type=schema 或 data 或 all - 指定要执行的 diff 类型，是模式、数据还是两者。schema 是默认值
• --include=up 或 down 或 all - 指定是否在输出中包含 up、down 或两者数据。up 是默认值
• --nocomments=true - 默认情况下，带有井号 (#) 字符自动生成的注释将包含在输出文件中，可以使用此参数删除
• --config=config.yaml - 默认情况下，DBDiff 将在当前目录中查找有效的 YAML 格式的 .dbdiff 文件，也可以用配置文件替换，该文件以 YAML 格式列出源和目标数据库的主机、用户、端口和密码（而不是使用命令行），或任何其他设置，例如格式、模板、类型、包含、nocomments。请注意：命令行参数将始终覆盖任何配置文件。
• server1.db1.table1:server2.db2.table3 或 server1.db1:server2.db2 - 最后一个参数是要比较的内容。此工具可以比较数据库中的一个表或所有表（整个数据库）
• --output=./output-dir/today-up-schema.sql - 最后一个参数是输出文件和/或目录，用于输出 diff，默认情况下将输出到命令运行的同一目录，如果没有指定目录。如果指定了目录，则该目录必须存在，否则将抛出错误。如果未指定此路径，则默认文件名变为当前目录中的 migration.sql

用法示例

示例 1

$ ./dbdiff server1.db1:server2.db2

这将默认查找 DB 连接详细信息的 .dbdiff 配置文件，如果没有找到，工具将返回错误。如果存在，将使用连接详细信息比较 SQL 模式，并输出一个带注释的 migration.sql 文件到当前目录，默认情况下只包含 up SQL

示例 2

$ ./dbdiff server1.development.table1:server2.production.table1 --nocomments=true --type=data

默认情况下，该工具会查找.dbdiff配置文件以获取数据库连接细节，如果找不到，则工具会返回错误。如果存在，则会使用连接细节来比较每个数据库中指定表1的数据的SQL语句，并在当前目录下输出一个无注释的.sql文件，默认情况下只包含向上SQL。

示例 3

$ ./dbdiff --config=config.conf --template=templates/simple-db-migrate.tmpl --include=all server1.db1:server2.db2 --output=./sql/simple-schema.sql

而不是查找.dbdiff，它将查找用于设置的config.conf （应为有效的YAML格式），然后覆盖config.conf 中指定的任何设置，包括命令行参数中的--template和--include参数，从而将源数据库与目标数据库进行比较，并将名为simple-schema.sql的SQL文件输出到./sql文件夹，该文件夹应已存在，否则程序将抛出错误，并且它只包含简单-db-migrate格式的schema（如模板中指定）的向上和向下SQL差异。此示例可以与simple-db-migrate工具完美配合使用。

文件示例

.dbdiff

server1:
	user: user
	password: password
	port: port # for MySQL this is 3306
	host: host1 # usually localhost or 127.0.0.1
server2:
	user: user
	password: password
	port: port # for MySQL this is 3306
	host: host1 # usually localhost or 127.0.0.1
template: templates/simple-db-migrate.tmpl
type: all
include: all
nocomments: true
tablesToIgnore:
- table1
- table2
- table3
fieldsToIgnore:
	table1:
		- field1
		- field2
		- field3
	table4:
		- field1
		- field4

simple-db-migrate.tmpl

SQL_UP = u"""
{{ $up }}
"""
SQL_DOWN = u"""
{{ $down }}
"""

差异是如何实际工作的？

以下比较将按照以下顺序运行

• 当比较多个表时：应运行所有比较
• 当比较一个表与另一个表时：仅运行模式和数据比较

总体比较

• 检查两个数据库是否存在且可访问，如果不存在，则抛出错误
• 然后比较源数据库和目标数据库的数据库校对，并将任何差异记录到输出中

模式比较

• 查看列数、名称、类型、校对或属性之间是否存在任何差异
• 在源数据库中添加新列，这些列在目标数据库中找不到

数据比较

• 然后，对于每个表，按顺序比较表存储类型（例如，MyISAM，CSV）、校对（例如，utf8_general_ci）和行数。如果有任何差异，它们将在进行下一个测试之前记录下来
• 接下来，记录每个表中更改的行以及缺失的行