Flyway项目Gradle插件使用指南

Flyway项目Gradle插件使用指南

flyway Flyway by Redgate • Database Migrations Made Easy. 项目地址: https://gitcode.com/gh_mirrors/fl/flyway

前言

Flyway是一款流行的数据库迁移工具，它通过简单、有效的方式管理数据库变更。本文将详细介绍如何在Gradle项目中使用Flyway插件，帮助开发者轻松实现数据库版本控制。

环境要求

在使用Flyway Gradle插件前，请确保满足以下环境要求：

• Gradle 7.6.x或8.x版本
• Java 17运行环境

注意：较早版本的Gradle由于依赖项问题可能无法正常工作。

插件安装

Flyway提供两种版本的Gradle插件：

社区版安装

社区版包含Teams和Enterprise功能，但需要遵守相关许可协议。在build.gradle文件中添加以下配置：

repositories {
    mavenCentral()
    maven {
        url "https://download.red-gate.com/maven/release"
    }
}
plugins {
    id "com.redgate.flyway" version "{{ site.flywayVersion }}"
}

开源版安装

如果只需要基础功能，可以使用开源版：

plugins {
    id "org.flywaydb.flyway" version "{{ site.flywayVersion }}"
}

核心任务

Flyway Gradle插件提供了一系列任务来管理数据库迁移：

| 任务名称 | 功能描述 | |-------------------|--------------------------------------------------------------------------| | flywayMigrate | 执行数据库迁移，将数据库升级到最新版本 | | flywayClean | 清除配置的schema中的所有对象（慎用） | | flywayInfo | 显示所有迁移的详细信息和状态 | | flywayValidate | 验证已应用的迁移与类路径上可用的迁移是否匹配 | | flywayUndo | 撤销最近应用的版本化迁移（仅限Teams/Enterprise版） | | flywayBaseline | 基线化现有数据库，排除基线版本之前的所有迁移 | | flywayRepair | 修复schema历史表 |

配置方式

Flyway Gradle插件支持多种灵活的配置方式，可以单独使用也可以组合使用。

基础配置（单数据库）

最简单的配置方式是在build.gradle中定义Flyway部分：

flyway {
    url = 'jdbc:h2:mem:mydb'
    user = 'myUsr'
    password = 'mySecretPwd'
    schemas = ['schema1', 'schema2', 'schema3']
    placeholders = [
        'keyABC': 'valueXYZ',
        'otherplaceholder': 'value123'
    ]
}

多数据库配置

如果需要管理多个数据库，可以扩展Flyway任务：

task migrateDatabase1(type: org.flywaydb.gradle.task.FlywayMigrateTask) {
    url = 'jdbc:h2:mem:mydb1'
    user = 'myUsr1'
    password = 'mySecretPwd1'
}

task migrateDatabase2(type: org.flywaydb.gradle.task.FlywayMigrateTask) {
    url = 'jdbc:h2:mem:mydb2'
    user = 'myUsr2'
    password = 'mySecretPwd2'
}

Java迁移和回调处理

使用Java迁移和回调时，需要确保在运行Flyway任务前编译相关类：

dependencies {
    implementation "org.flywaydb:flyway-core:${flywayVersion}"
}

flyway {
    url = 'jdbc:h2:mem:mydb'
    user = 'myUsr'
    password = 'mySecretPwd'
    locations = ['classpath:db/migration']
}

// 确保先编译类再执行迁移
flywayMigrate.dependsOn classes

扩展类路径

默认情况下，插件使用Gradle的标准配置类路径。如需扩展：

configurations {
    flywayMigration
}

dependencies {
    implementation "org.flywaydb:flyway-core:${flywayVersion}"
    flywayMigration "com.mygroupid:my-lib:1.2.3"
}

flyway {
    configurations = [ 'compileClasspath', 'flywayMigration' ]
    // 其他配置...
}

数据库驱动依赖

某些数据库类型需要额外添加依赖：

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.flywaydb:flyway-mysql:{{ site.flywayVersion }}"
    }
}

工作目录注意事项

当JDBC URL中使用相对路径时，路径是相对于~/.gradle/目录的。建议使用绝对路径：

flyway {
    url = "jdbc:h2:file:${System.getProperty('user.dir')}/<database>"
    user = <user>
}

高级配置方式

Gradle属性配置

可以通过命令行或gradle.properties文件传递配置：

命令行方式：

gradle -Pflyway.user=myUsr -Pflyway.schemas=schema1,schema2

或gradle.properties文件：

flyway.user=myUser
flyway.password=mySecretPwd
flyway.schemas=schema1,schema2,schema3
flyway.placeholders.keyABC=valueXYZ

环境变量配置

Flyway支持通过环境变量配置，便于云和容器化环境使用。

系统属性配置

直接通过命令行传递JVM系统属性：

gradle -Dflyway.user=myUser -Dflyway.schemas=schema1,schema2

配置文件支持

Flyway会自动加载<user-home>/flyway.conf配置文件。也可以指定自定义配置文件：

gradle -Dflyway.configFiles=path/to/myAlternativeConfig.conf flywayMigrate

多个文件用逗号分隔：

gradle -Dflyway.configFiles=path/to/myAlternativeConfig.conf,other.conf flywayMigrate

配置加载顺序

Flyway按以下优先级加载配置（从高到低）：

1. 系统属性
2. 环境变量
3. 自定义配置文件
4. Gradle属性
5. build.gradle中的Flyway配置
6. <user-home>/flyway.conf
7. 插件默认值

最佳实践

1. 敏感信息处理：密码等敏感信息建议通过环境变量或安全配置管理工具传递
2. 多环境支持：利用Gradle的不同构建类型或配置文件管理不同环境的数据库配置
3. 迁移脚本命名：遵循Flyway的命名约定（如V1__Initial_version.sql）
4. 版本控制：将迁移脚本与应用程序代码一起纳入版本控制
5. 回滚策略：提前规划好数据库变更的回滚方案

通过合理配置Flyway Gradle插件，开发者可以轻松实现数据库变更的自动化管理，提高开发效率和系统可靠性。

flyway Flyway by Redgate • Database Migrations Made Easy. 项目地址: https://gitcode.com/gh_mirrors/fl/flyway