README

DBDiff 是一个自动化的数据库模式和数据差异工具。它比较两个数据库（本地或远程），并自动生成差异迁移文件。

当与兼容的数据库迁移工具配合使用时，它可以帮助在您的团队或企业内部实现数据库版本控制。

支持 DBDiff

DBDiff 是一个 MIT 许可的开源项目，其持续发展完全由赞助者的支持实现。为了获得回报，请考虑以下选项：

• 在 Patreon 上成为赞助者或赞助商.
• 通过 PayPal 进行一次性捐赠
• 如果您是个人、公司或组织，并希望为 DBDiff 购买商业支持包，请联系我们 https://akalsoftware.com/contact-us/

功能

• 由于是用 PHP 开发的，因此它在 Windows、Linux 和 Mac 的命令行/终端上运行
• 连接到源数据库和目标数据库以进行比较差异，本地和远程均可
• 差异可以包括对模式和/或数据的更改，包括有效的 SQL 以将目标数据库更新到与源数据库一致
• 在配置文件中的 YAML 集合中可以忽略一些表和/或字段（请参阅文件示例）
• 差异非常快，并且该工具已经与包含数百万行表的数据库进行过测试
• 由于此差异工具用于迁移，因此它在同一文件中提供向上和向下的 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:DBDiff/DBDiff.git

或者 使用 git 克隆 https 版本

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

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

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

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

php composer.phar require "dbdiff/dbdiff:@dev"

或者 使用 composer 全局安装 DBDiff

composer global require "dbdiff/dbdiff:@dev"

创建 PHAR 构建

请首先确保在您的 php.ini 文件中 phar.readonly 设置设置为 false ，例如

[Phar]
; https://php.ac.cn/phar.readonly
phar.readonly = false

然后在 dbdiff 仓库的根目录下运行以下命令以生成 Phar 构建

$ ./build

应创建一个包含以下文件的 dist 文件夹

• dbdiff.phar
• dbdiff.phar.gz

您可以将 dbdiff.phar 重命名为 dbdiff 并将其移动到 /usr/local/bin 或您选择的另一个目录。

如果您希望将此工具作为系统级别的实用程序全局使用，也可以将其添加到系统路径中。

设置

请确保您位于应用程序的根目录，以下所有步骤都需要这样做，使用 '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 - 指定要做的差异类型，是模式、数据还是两者。默认为 schema
• --include=up 或 down 或 all - 指定是否在输出中包含 up、down 或两者数据。默认为 up
• --nocomments=true - 默认情况下，以井号 (#) 字符开头的自动注释将包含在输出文件中，可以使用此参数将其删除
• --config=config.yaml - 默认情况下，DBDiff 将在当前目录中查找有效的 YAML 格式的 .dbdiff 文件，也可以用配置文件来覆盖，该配置文件以 YAML 格式列出源和目标数据库的数据库主机、用户、端口和密码（而不是使用命令行），以及其他设置，例如格式、模板、类型、包含、无注释。请注意：命令行参数将始终覆盖任何配置文件。
• server1.db1.table1:server2.db2.table3 或 server1.db1:server2.db2 - 最后一个参数是要比较的内容。此工具可以比较数据库中的单个表或所有表（整个数据库）
• --output=./output-dir/today-up-schema.sql - 最后一个参数是输出文件和/或目录，将差异输出到该文件和/或目录，默认情况下将输出到命令运行的同一目录，如果没有指定目录。如果指定了目录，则该目录必须存在，否则将引发错误。如果没有指定此路径，默认文件名将成为当前目录下的 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），用于设置，然后覆盖命令行参数中给出的--template和--include参数的任何设置，从而将源数据库与目标数据库进行比较，并将名为simple-schema.sql的SQL文件输出到./sql目录中，该目录应已存在，否则程序会抛出错误，并且该文件仅包含简单-db-migrate格式（由模板指定）中的向上和向下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）和行数。如果有任何差异，则在进行下一个测试之前记录这些差异
• 接下来，记录每个表中的更改行以及缺失的行

兼容迁移工具

如果您使用DBDiff的其他迁移工具（而非此处列出的工具），请告诉我们，以便我们可以添加它。

问题 & 支持 💭

• 如果您找不到自己的问题 被解决，请创建一个新的问题
• 请关注这个空间，因为我们正在创建一个讨论区，供所有DBDiff社区成员使用

• 到目前为止的文档就是您在这个页面上看到的，然而这将逐渐扩展到其自己的网站

• 如果您是公司或组织，对DBDiff感兴趣并希望获取商业支持包，请联系我们

赞助者 💕

Sean McNamara

在Patreon上赞助DBDiff，并让您的名字或标志在这里突出显示！

贡献 💞

在提交拉取请求之前，请务必阅读贡献指南。

感谢所有已经为DBDiff做出贡献的人！

反馈 💬

如果您已经看到这里，您可能是个粉丝 😉

请您抽出2分钟时间，为我们提供有关DBDiff的反馈

https://forms.gle/gjdJxZxdVsz7BRxg7

我们阅读每个通过的建议。

许可证

MIT

由  :heart:  制作，由 提供