Dropwizard Migrations 测试数据库维护指南：重建与同步 H2 的 `test-db.mv.db`-育师

后端
Web框架

【免费下载链接】dropwizard

A damn simple library for building production-ready RESTful web services.

项目地址：https://gitcode.com/gh_mirrors/dr/dropwizard

在 Dropwizard 的dropwizard-migrations模块中，单元测试依赖一个预先迁移完成的 H2 文件数据库test-db.mv.db来验证db status、db dump等命令行行为；当 H2 主版本升级导致存储格式变化，或 Liquibase changelog 变更时，这个文件（以及它的 SQL 备份源文件test-db-backup.sql）需要重建。本文基于 create_test_db.md 这份维护说明，结合 dropwizard-migrations 模块的 pom.xml 与相关测试源码，完整讲解何时需要重建、如何用 H2 的RunScript/Script工具手工重建、Maven 自动化是如何落地的，以及如何验证重建结果的正确性。

为什么需要一个"已迁移完成"的 H2 文件数据库

dropwizard-migrations是对 Liquibase 的封装（官方手册见 migrations.rst），对外提供db migrate、db status、db dump等一系列 CLI 命令。其中一些命令（如db status、db dump）的正确性验证需要一个已经执行过全部 changeset的数据库作为输入，而不能每次测试都从零迁移。因此模块在测试资源目录中保留了一个"成品"数据库文件，其 SQL 备份源文件为 test-db-backup.sql。

从该备份文件的内容可以看到，这个数据库里恰好包含验证db status所需的全部要素：

Liquibase 的元数据表DATABASECHANGELOGLOCK（锁定表）与DATABASECHANGELOG（执行记录表），其中记录了migrations.xml中 3 个 changeset 的EXECUTED状态（1/2/3，作者db_dev，对应 Liquibase 3.3.3）；
业务表PERSONS，包含一条种子数据(1, 'Bill Smith', 'bill@smith.me')——这正是 migrations.xml 中 changeset1（createTable persons）、2（addColumn email）、3（insert Bill Smith）执行后的最终形态。

测试代码通过类路径直接定位该文件：DbStatusCommandTest.java 与 DbDumpCommandTest.java 都使用getClass().getResource("/test-db.mv.db")取到文件 URI，再把路径去掉结尾的.mv.db拼成 H2 的 JDBC URL（jdbc:h2:<path>），交给 MigrationTestSupport.java 构建DataSourceFactory配置。也就是说，只要test-db.mv.db文件本身存在且内容是"迁移完成态"，这套测试就能工作。

触发重建的条件：H2 主版本升级

create_test_db.md 首先指出：如果 H2 发生了主版本升级（major upgrade），test-db.mv.db的存储格式可能发生变化，旧文件可能无法被新版本的 H2 引擎正常打开，此时必须重新创建一个数据库文件。

一个佐证细节是备份文件首行注释-- H2 2.1.214;——当前仓库中该备份是由 H2 2.1.214 导出的；而 dropwizard-dependencies/pom.xml 中实际管理的<h2.version>为2.4.240。备份 SQL 本身是版本无关的（纯 DDL + DML），这正是"以 SQL 备份为源、按需重建二进制文件"这一维护策略成立的前提。

手动重建：使用 H2 的`RunScript`工具

从 SQL 备份文件重建数据库，使用 H2 自带的org.h2.tools.RunScript命令行工具。它的作用是把一个 SQL 脚本文件回放（replay）到一个（新的或已存在的）数据库上，等价于"从备份文件创建一个数据库"：

java -cp <path_to_h2.jar> org.h2.tools.RunScript -user sa -url jdbc:h2:file:./test-db -script ./test-db-backup.sql

各参数含义：

参数	说明
`-cp <path_to_h2.jar>`	H2 引擎 jar 的路径，当前仓库依赖版本为 2.4.240（见 dropwizard-dependencies/pom.xml）
`-user sa`	以`sa`用户连接（H2 默认管理员用户，备份文件中也包含`SA`用户的建号语句）
`-url jdbc:h2:file:./test-db`	目标数据库的文件型 JDBC URL。H2 2.x 默认使用 MVStore 引擎，会自动在基名后追加`.mv.db`后缀，即生成`test-db.mv.db`
`-script ./test-db-backup.sql`	要回放的 SQL 备份脚本

执行成功后，工作目录下会生成test-db.mv.db（必要时还有对应的.trace.db等辅助文件），把二进制文件放入src/test/resources/即完成重建。

Maven 自动化：`exec-maven-plugin`的落地

文档中说明：自 Dropwizard 2.1.8 / 3.0.2 / 4.0.2 起，数据库文件的重建已经通过exec-maven-plugin自动化，无需手工执行上面的java命令。这一点可以直接在 dropwizard-migrations/pom.xml 中得到印证：

<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>exec-maven-plugin</artifactId> <configuration> <includePluginDependencies>true</includePluginDependencies> <mainClass>org.h2.tools.RunScript</mainClass> <arguments> <argument>-user</argument> <argument>sa</argument> <argument>-url</argument> <argument>jdbc:h2:file:${project.basedir}/src/test/resources/test-db</argument> <argument>-script</argument> <argument>${project.basedir}/src/test/resources/test-db-backup.sql</argument> </arguments> </configuration> <executions> <execution> <id>test-db-creation</id> <phase>generate-test-resources</phase> <goals> <goal>java</goal> </goals> </execution> </executions> <dependencies> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <version>${h2.version}</version> </dependency> </dependencies> </plugin>

这段配置与文档中的手工命令一一对应：mainClass同为org.h2.tools.RunScript，参数同为-user sa、-url jdbc:h2:file:.../test-db、-script .../test-db-backup.sql，只是把<path_to_h2.jar>换成了插件自带的 H2 依赖（${h2.version}= 2.4.240）。两个关键设计值得注意：

绑定到generate-test-resources阶段：任何触发测试资源准备的生命周期（如mvn test）都会先自动执行RunScript，从test-db-backup.sql重建出test-db.mv.db。因此即使开发者本地没有这个二进制文件，或 H2 版本切换后旧文件失效，构建也能自愈。
与clean阶段配合：同文件下方还配置了 maven-clean-plugin 的自定义 fileset（execution id 为clean-test-db，绑定initialize阶段），在mvn clean时删除src/test/resources/test-db.mv.db。二者配合保证每次构建中的数据库文件都来自最新的 SQL 备份，而不是残留的旧产物。

Liquibase changelog 变更时：如何更新`test-db-backup.sql`

第二个维护场景是：当 Liquibase 的 changelog（migrations.xml等）发生变更——例如新增 changeset、调整表结构或种子数据——test-db-backup.sql所描述的"迁移完成态"就会过时，需要同步刷新。create_test_db.md 给出的流程分两步：

用一个全新的干净数据库执行迁移：即用更新后的 changelog（migrations.xml）对空库跑一遍 Liquibase 迁移，得到迁移后的数据库（假设为new-migrated-db）。这一步可以用dropwizard-migrations自身的db migrateCLI 完成，也可以用 H2 的RunScript回放 migrations-ddl.xml 等 DDL 变更集；
用 H2 的Script工具导出新的备份：

java -cp <path_to_h2.jar> org.h2.tools.Script -user sa -url jdbc:h2:file:./new-migrated-db -script ./test-db-backup.sql

org.h2.tools.Script与RunScript方向相反：它把当前数据库的完整结构（建表语句、主键约束）和数据（INSERT语句，含-- N +/- SELECT COUNT(*)行数注释）序列化写入-script指定的文件。用新导出的内容覆盖 test-db-backup.sql，DATABASECHANGELOG表中就会记录新 changelog 的 changeset 摘要（如新的 MD5SUM），备份文件与 changelog 重新保持一致。

验证重建结果：从测试源码看"迁移完成态"的判定

重建完成后，可以用两条途径验证test-db.mv.db确实处于预期状态：

db status应报告"已最新"：DbStatusCommandTest.java 的testRunOnMigratedDb测试从类路径取出test-db.mv.db，对其中数据运行DbStatusCommand，断言输出匹配\S+ is up to date。若备份文件中记录的 changeset 与 changelog 不一致（比如 MD5 校验和变化），状态会变为"有 N 个 changeset 未执行"甚至报告待回滚，测试即失败。
db dump应能还原出表结构与数据：DbDumpCommandTest.java 对同一文件数据库执行DbDumpCommand，断言导出的 Liquibase XML 中包含PUBLIC.PERSONS表（ID自增主键、NAME非空、EMAIL）以及Bill Smith这条插入数据。这从另一个角度确认了数据库的表结构与种子数据正确。

因此，一次完整的维护闭环是：changelog 变更 → 空库迁移 →Script重新导出test-db-backup.sql；H2 版本变更 →RunScript从备份重建test-db.mv.db（或由exec-maven-plugin自动完成）→ 运行db status/db dump相关测试确认断言全部通过。

文件	说明
dropwizard-migrations/src/test/resources/create_test_db.md	本文对应的原始维护说明
dropwizard-migrations/src/test/resources/test-db-backup.sql	数据库的 SQL 备份源文件（H2 2.1.214 导出）
dropwizard-migrations/src/test/resources/migrations.xml	测试用 Liquibase changelog（3 个 changeset）
dropwizard-migrations/pom.xml	`exec-maven-plugin`重建与`clean`清理配置
dropwizard-migrations/src/test/java/io/dropwizard/migrations/DbStatusCommandTest.java	验证迁移完成态的测试
dropwizard-migrations/src/test/java/io/dropwizard/migrations/DbDumpCommandTest.java	验证 dump 输出内容与结构的测试
docs/source/manual/migrations.rst	`dropwizard-migrations`模块的用户手册