在 maven 项目中添加 flyway 依赖，纯 java 项目需显式引入 flyway-core，spring boot 项目应优先使用 spring-boot-starter-flyway；注意版本兼容性、配置项前缀（flyway.*）、sql 脚本命名规范及 migrate 调用时机。
怎么在 Maven 项目里加 Flyway 依赖
Java 项目用 Flyway，第一步不是写 SQL，是让编译器认得它。Maven 项目必须显式声明 flyway-core，否则 Flyway.configure() 会直接报 NoClassDefFoundError。
注意：别只加 flyway-maven-plugin——那是给命令行用的，运行时迁移必须靠 flyway-core。
- Spring Boot 用户优先用
spring-boot-starter-flyway，它自动拉取匹配版本的flyway-core - 纯 Java（非 Spring）项目，选和你 JDBC 驱动兼容的 Flyway 版本：Flyway 9+ 要求 Java 11+，且不兼容旧版 H2 的
mem:URL 格式 - 如果项目里已有 Hibernate，确认
flyway-core和hibernate-core没有冲突的 Guava 或 commons-lang 版本（常见于 Flyway 7.x + Hibernate 5.4）
配置文件里哪些 key 真的会被读到
Flyway 不读 application.properties 里的所有字段，只认自己定义的前缀。比如 spring.flyway.* 是 Spring Boot 封装后的路径，原生 Flyway 只认 flyway.*，且仅限于它文档里列出的那些 key。
常见失效配置：flyway.locations=classpath:db/migration 写成 flyway.location（少个 s）、flyway.url 指向了没权限的数据库、或把 flyway.schemas 设成不存在的 schema 名导致启动卡住。
立即学习“Java免费学习笔记（深入）”；
-
flyway.url必须带协议和完整参数，例如jdbc:postgresql://localhost:5432/mydb?currentSchema=public；MySQL 要加useSSL=false&serverTimezone=UTC否则连不上 -
flyway.user和flyway.password是明文，生产环境建议用系统属性或环境变量传入，避免硬编码 -
flyway.table默认是flyway_schema_history，改名前确认目标数据库支持该标识符长度（Oracle 限制 30 字符）
SQL 迁移脚本命名为什么总被跳过
Flyway 对文件名极其敏感，错一个字符、多一个空格、大小写不一致，都会导致脚本被忽略——它不会报错，只是安静地当它不存在。
典型现象：启动后日志显示 Successfully validated 0 migrations，或者执行了 V1__xxx.sql 却跳过了 V2__yyy.sql。
- 必须以
V或R开头，后接数字（支持点号分隔，如V1.2.3__add_index.sql），再双下划线__，再描述，最后是.sql - 文件名不能含中文、括号、空格；Windows 下容易生成
V1__init.sql.txt（隐藏扩展名），实际是文本文件而非 SQL - 重复执行同一版本会报
Validation failed，除非设flyway.validateOnMigrate=false（不推荐）
Java 代码里手动触发 migrate 的坑
不用 Spring Boot 时，得自己 new Flyway 实例并调用 migrate()。但顺序错了就白干：比如在 DataSource 初始化前调用，或在事务里调用，会导致锁表失败或连接泄漏。
最常被忽略的是：Flyway 默认使用自己的连接池，和你的应用连接池无关。如果 DataSource 已关闭，migrate() 会抛 SQLException: Connection is closed。
- 确保
Flyway.configure().dataSource(...)传的是可用的、未关闭的DataSource实例，不是字符串 URL - 不要在
@PostConstruct或静态块里调用migrate()，此时 Spring 上下文可能还没准备好 DataSource Bean - 如果要跳过某次迁移（比如本地开发），用
flyway.baselineOnMigrate=true+flyway.baselineVersion=1.0，而不是删flyway_schema_history表
迁移不是“配完就能跑”，关键是每个环节都得对上 Flyway 的校验节奏——它不报错，不代表它在干活。
