Flyway 实现数据库版本自动化迁移的核心是将 SQL 脚本与代码统一 Git 管理、按序执行、可追踪复现；需正确引入依赖（如 spring-boot-starter-flyway）、配置关键参数（如 locations、baseline-on-migrate）、编写合规脚本（V/R/U 前缀、规范命名），并理解其启动时自动执行、不替代 ORM 的行为边界。

Java 项目中用 Flyway 实现数据库版本自动化迁移，核心是让 SQL 脚本和应用代码一起受 Git 管理、按序执行、有据可查。它不依赖 ORM 的自动建表能力，而是把数据库变更变成可追踪、可复现的工程动作。

添加正确依赖

依赖选错或漏加，项目根本跑不起来：

• Spring Boot 项目优先用 spring-boot-starter-flyway，它会自动引入匹配版本的 flyway-core 和适配器（如 MySQL、PostgreSQL）
• 纯 Java（非 Spring）项目必须显式声明 flyway-core，仅加 flyway-maven-plugin 不起作用
• MySQL 用户额外确认驱动兼容性：mysql-connector-j 8.0+，URL 中带上 useSSL=false&serverTimezone=UTC
• 若项目已用 Hibernate，留意 Flyway 7.x 与 hibernate-core 5.4 可能因 Guava 版本冲突导致启动失败

配置关键参数

Flyway 只认自己定义的配置前缀，写错字段名或路径就静默失效：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• spring.flyway.locations（Spring Boot）或 flyway.locations（原生）必须设为脚本目录，如 classpath:db/migration
• spring.flyway.baseline-on-migrate=true：对已有生产库首次接入时必需，否则报“schema not empty”错误
• spring.flyway.validate-on-migrate=true（推荐开启）：每次启动校验脚本 checksum，提前发现被篡改的 V 脚本
• spring.flyway.clean-disabled=true：生产环境必须显式设置，禁用危险的 clean 操作
• 数据库连接参数（url/user/password）要完整准确，尤其注意 MySQL 的时区和 SSL 参数

编写合规迁移脚本

文件名错一个字符，Flyway 就当它不存在——不报错、不提示、只跳过：

立即学习“Java免费学习笔记（深入）”；

• 前缀只能是 V（版本化）、R（可重复）、U（回滚），大小写敏感
• 版本号后接两个下划线 __，再写描述，如 V1__create_user_table.sql
• 版本号支持点分隔：V2.1__add_phone_column.sql 合法，但 V2_1（单下划线）会被忽略
• 文件名不能含中文、空格、括号；Windows 下警惕隐藏扩展名（如 V1.sql.txt）
• V 脚本一旦执行过，绝对禁止修改内容——改了就触发 checksum mismatch 报错

理解执行时机与行为边界

Flyway 是启动时自动运行的，但它不管业务逻辑，也不替代 ORM：

• 脚本默认在 Spring Boot ApplicationContext 刷新前执行，无需手动调用 migrate()
• 它只管 DDL（建表、加字段）和 DML（初始化数据），不生成业务 SQL，不映射实体，不处理查询
• R 脚本（如视图、函数）每次启动都重执行，但不参与版本排序，也不能替代 V 脚本做结构变更
• 多数据源需为每个 DataSource 显式配置独立的 Flyway Bean，不能共用一个实例