在 maven 项目中添加 flyway 依赖需引入 flyway-core（如 9.22.3 或 8.5.13），spring boot 推荐使用 spring-boot-starter-flyway 并注意版本冲突；sql 脚本须置于 src/main/resources/db/migration，命名格式为 v{major}_{minor}__{description}.sql；开发可设 flyway.skip=true 跳过执行，生产 baseline 需首次用 flyway baseline -baselineversion=1.0 安全接入已有库。
怎么在 Maven 项目里加 Flyway 依赖
Java 项目用 Flyway，第一步不是写 SQL，是让项目“认得”它。Maven 里漏掉 flyway-core 或版本不匹配，后续所有配置都白搭。
常见错误现象：ClassNotFoundException: org.flywaydb.core.Flyway，或者 Spring Boot 启动时压根不扫描 migration 脚本。
- Spring Boot 3.x 推荐用
org.flywaydb:flyway-core:9.22.3（与 Jakarta EE 9+ 兼容）；Boot 2.7.x 及以前用8.5.13更稳 - 别只加
flyway-mysql这类方言包——flyway-core才是主干，方言包只在需要自定义连接器时才额外引入 - 如果用 Spring Boot，
spring-boot-starter-flyway已包含 core，但要注意它的版本是否和你手动指定的flyway-core冲突（Maven 会取 nearest-wins，容易隐式降级）
SQL 迁移脚本放哪、怎么命名才被识别
Flyway 不靠配置文件“注册”脚本，而是靠目录路径 + 命名规则自动发现。放错位置或名字格式错一个字符，脚本就静默失效。
使用场景：本地开发改表结构、CI 环境跑测试库、生产发布前校验 baseline。
立即学习“Java免费学习笔记（深入）”；
- 默认路径是
src/main/resources/db/migration；可改，但必须配flyway.locations=classpath:db/migration - 命名必须是
V{major}_{minor}__{description}.sql格式，比如V1_0__add_user_table.sql；双下划线__是分隔符，不能写成_或空格 - 版本号只支持数字和点（
V1.2合法，V1-2非法），且不能跳号（V1 → V3 会报Repair needed） - 重复执行同一版本脚本会失败；想重跑得先
flyway repair（慎用，生产禁用）
怎么跳过某次迁移或临时禁用 Flyway
开发调试时经常要绕过某条 SQL（比如某个耗时长的索引重建），但又不想删脚本——直接注释或改名会破坏版本连续性。
参数差异：flyway.enabled=false 是全局关，flyway.skip=true 是跳过执行但保留扫描逻辑（用于测试环境快速启动）。
- 最安全的做法是加
flyway.ignoreMissingMigrations=true，再配合flyway.baseline-on-migrate=true处理已有库 - 临时禁用：Spring Boot 中设
spring.flyway.enabled=false；纯 Java 代码中初始化Flyway实例时不要调migrate() - 注意
flyway.cleanDisabled=true必须显式设为true，否则flyway clean命令默认拒绝执行（防误删生产数据）
生产环境 baseline 怎么设才不炸库
老系统接入 Flyway，数据库已有几十张表和数据，这时不能从 V1 开始跑——baseline 就是告诉 Flyway：“这些表我不管，从 V2 开始管”。设错就等于把现有表当新表清空。
容易踩的坑：用 flyway repair 强制修复 checksum，或在非空库上直接 migrate，都会触发 Schema History table not found 报错然后卡死。
- 先确保目标库为空，或已手动建好
flyway_schema_history表（Flyway 8+ 默认表名，别手误写成schema_version） - 执行
flyway baseline -baselineVersion=1.0 -baselineDescription="existing_db"，这会在 history 表里插一条记录，标记 V1.0 已完成 - baselineVersion 必须小于你第一个真实迁移脚本的版本号（如首个脚本是
V1_1__xxx.sql，baseline 就只能设1.0或1） - baseline 操作不可逆，且只应在首次接入时执行一次；后续所有环境（包括测试库）都要复用同一 baseline 版本
baseline 的 version 字段看着像语义化版本，其实只是字符串比较；V2 和 V10 在 Flyway 里谁大谁小，取决于字典序，不是数值大小——这点在跨团队协作时最容易出事。
