当前位置：首页 > news >正文

Spring Boot中如何使用Flyway进行数据库迁移

news 2025/7/15 15:06:26

在本文中，我们将了解如何使用 Flyway 来管理 Spring Boot 应用程序中的 SQL 数据库架构。

在本文中，我们将了解如何使用 Flyway 来管理Spring Boot应用程序中的SQL 数据库架构。
Flyway是一个数据库迁移工具，它提供迁移历史和回滚的功能，并允许我们将应用程序的数据库模式相关层与数据库实体层分离。

应用程序设置

我们将使用的 Spring Boot 应用程序可以使用此Spring Initializr链接生成。它包含所有必要的依赖项。
下载应用程序并解决依赖关系后，我们将创建一个名为spring-boot-flyway的新 Postgres 数据库，并配置应用程序以连接到它。

清单 2.1 application.properties：

spring.datasource.url=jdbc:postgresql://localhost:5432/spring-boot-flyway
spring.datasource.username=demo
spring.datasource.password=demo

默认情况下，Flyway 会在类路径中的db/migration/目录中搜索包含用于管理数据库表和记录的 SQL 语句的迁移文件。

对于旧版本的库，我们可能需要在resources/db/migration/ 中创建一个名为.keep的空文本文件，以确保该目录在应用程序启动期间被编译并可用，以避免错误。

完成此操作后，我们现在可以启动应用程序并且它应该成功运行。

基本用法

Flyway 的工作方式是，我们在resources/db/migration目录中创建一个迁移文件，Spring Boot 会自动执行迁移脚本，因为我们已经在第 2 节中将 Flyway 依赖项添加到了类路径中。

清单3.1 V1__Users.sql：

CREATE TABLE IF NOT EXISTS users
(id    SERIAL,email VARCHAR(200) NOT NULL,name  VARCHAR(200) NOT NULL,PRIMARY KEY (id)
);

让我们花一点时间来检查一下清单 3.1 中的代码片段。文件名V1__Users.sql遵循一定的约定：

“ V ”表示这是版本化迁移。
V后面的“ 1 ”是实际版本号。它也可以是“ V1_1 ”，这将转换为版本 1.1。
后面是分隔符“ __ ”（两个下划线）。这会将版本信息与迁移文件的名称（在本例中为Users ）分开。
最后一部分“ .sql ”是扩展名；因此，该文件包含一个简单的 SQL 语句。

此时，重新启动应用程序将在数据库中创建用户表。此外，我们可以看到还有另一个我们没有显式创建的表 - Flyway_schema_history 。

Flyway_schema_history由 Flyway 本身用来跟踪已应用的迁移。如果该表丢失，Flyway 将假设我们是第一次初始化数据库，并按照版本号的顺序运行所有迁移。

当Flyway_schema_history表存在时，Flyway 将仅应用之前未应用过的较新的迁移文件。这意味着，为了添加新表，我们只需创建具有更新版本号的更新的迁移文件并重新启动应用程序。

除了使用 SQL 之外，我们还可以使用Java编写迁移脚本。在Java迁移风格中，我们的迁移文件是Java类，必须扩展抽象BaseJavaMigration类并实现migrate方法。

IDE 通常不希望 Java 类位于resources目录中，因此我们将在src/main/java中创建一个名为db/migration的新包。非常重要的是要知道这个新包db/migration应该位于src/main/jav目录中。

让我们创建一个新的 Java 迁移来添加新表：

清单 3.2 V2__Posts.java ：

public class V2__Posts extends BaseJavaMigration {@Overridepublic void migrate(Context context) throws Exception {var sql = """CREATE TABLE posts (id SERIAL,author_id INT NOT NULL,post TEXT NOT NULL,created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,PRIMARY KEY (id));""";try(var statement = context.getConnection().createStatement()) {statement.execute(sql);}}
}

与 SQL 文件相比，使用 Java 迁移的优点是我们可以添加使用普通 SQL 无法实现的自定义逻辑、条件和验证。例如，我们可以检查另一个表是否存在或从环境中获取某些值等。

正如您现在可能猜到的那样，是的，可以在同一个代码库中混合 SQL 和 Java 风格的迁移，只要我们确保两种情况下的 Flyway 位置相同。

Flyway配置和定制

到目前为止，我们一直在使用默认的 Flyway 行为。我们可以进一步调整 Flyway 以满足我们的需求。例如，我们可以更改迁移文件的默认位置、配置数据库架构（也称为表空间）、将 SQL 迁移前缀从“V”更改为我们想要的任何内容等等。

在下面的配置中，我们配置了迁移文件所在的路径并禁用清理数据库（即删除所有表）以防止在生产环境中意外使用。

清单4.1 application.properties：

spring.flyway.locations=classpath:migrations
spring.flyway.clean-disabled=true

该键下还有其他可配置属性spring.flyway，我们可以使用它们来微调库的行为。另外，我们可以查阅Flyway 文档页面以供参考。

飞行路线回调

Flyway为我们提供了配置回调的能力，这些回调可以在迁移过程的不同阶段调用。回调机制是在迁移生命周期的不同阶段执行某些操作的便捷方法。

假设我们有一些默认数据想要在应用程序启动时播种。我们可以简单地创建一个支持该AFTER_MIGRATE事件的回调。

清单 5.1 FlywayDatabaseSeeder.java：

public class FlywayDatabaseSeeder implements Callback {@Overridepublic boolean supports(Event event, Context context) {return event.name().equals(Event.AFTER_MIGRATE.name());}@Overridepublic void handle(Event event, Context context) {try(var statement = context.getConnection().createStatement()) {var ADMIN_EMAIL = "superadmin@example.com";var checkQuery = "SELECT id FROM users WHERE email = %s".formatted(ADMIN_EMAIL);statement.execute(checkQuery);ResultSet resultSet = statement.getResultSet();resultSet.last();//return if the seeder has already been executedif(resultSet.getRow() >= 0) return;var sql = """INSERT INTO users (email, name) VALUES('%s', 'Super Admin')""".formatted(ADMIN_EMAIL);statement.execute(sql);} catch (SQLException e) {throw new RuntimeException(e);}}@Overridepublic boolean canHandleInTransaction(Event event, Context context) {return true;}@Overridepublic String getCallbackName() {return FlywayDatabaseSeeder.class.getName();}
}

在上面的清单中，在supports方法中，我们声明只应针对AFTER_MIGRATE事件执行此回调，并且在handle方法中，我们概述了插入默认超级管理员用户（如果尚不存在）的逻辑。

在这之前，我们需要在 SpringBoot 中向 Flyway 注册回调类。我们通过创建一个FlywayMigrationStrategybean 来做到这一点。

清单 5.2 SpringBootFlywayApplication.java ：

@Bean
public FlywayMigrationStrategy flywayMigrationStrategy() {return (flywayOld) -> {/*Update the existing autoconfigured Flywaybean to include our callback class*/Flyway flyway = Flyway.configure().configuration(flywayOld.getConfiguration()).callbacks(new FlywayDatabaseSeeder()).load();flyway.migrate();};
}

rg.flywaydb.core.api.callback.Event枚举中还有其他事件，我们可以配置Callback类来支持。例如，您可以有一个回调来支持该AFTER_MIGRATE_ERROR事件并发送 Slack 通知来提醒工程师。

技巧和窍门

在本地环境中进行开发时，您可以从Flyway_schema_history表中删除迁移条目。

下次启动应用程序时，您删除其历史记录的迁移将再次执行。这样，您可以更正错误或更新架构，同时仍在本地计算机上进行开发，而无需删除整个数据库。

此外，在 SpringBoot 中，您可以控制 Flyway 在应用程序启动时何时执行迁移脚本。例如，假设我们不希望在本地环境中自动执行迁移。我们可以执行以下操作：

清单6.1 SpringBootFlywayApplication.java：

@Bean
public FlywayMigrationStrategy flywayMigrationStrategy(@Value("${spring.profiles.active}") String activeProfile) {return (flywayOld) -> {/*Update the existing autoconfigured Flywaybean to include our callback class*/Flyway flyway = Flyway.configure().configuration(flywayOld.getConfiguration()).callbacks(new FlywayDatabaseSeeder()).load();if(!"local".equalsIgnoreCase(activeProfile)) {flyway.migrate();}};
}