Flyway项目在Azure SQL Server 12.0上的兼容性问题解析

问题背景

在Spring Boot应用升级过程中，开发者遇到了Flyway与Azure SQL Server 12.0的兼容性问题。具体表现为：当应用从Spring Boot 2.6.15升级到更高版本时，Flyway在本地开发环境（SQL Server 15）运行正常，但在Azure环境（SQL Server 12.0）却抛出"Unsupported Database: Microsoft SQL Server 12.0"异常。

问题现象

开发者尝试了多个Spring Boot和Flyway版本组合：

1. Spring Boot 2.7.x + Flyway 8.5.x
2. Spring Boot 3.0.13 + Flyway 9.5.1
3. Spring Boot 3.1.12 + Flyway 9.16.3
4. Spring Boot 3.2.12 + Flyway 9.22.3
5. Spring Boot 3.3.10 + Flyway 10.10.0
6. Spring Boot 3.4.4 + Flyway 10.20.1

所有组合在本地环境都能正常工作，但在Azure SQL Server 12.0环境下均失败，错误信息一致。

问题根源

经过深入排查，发现问题出在Gradle依赖配置上。开发者最初使用的是compileOnly指令引入flyway-sqlserver依赖：

compileOnly 'org.flywaydb:flyway-sqlserver'

这种配置方式在IntelliJ IDEA开发环境中可以正常工作，但在生产环境（如Azure/Docker）中会导致Flyway无法正确加载SQL Server特定的实现类。这是因为compileOnly依赖不会被打包到最终的应用中，只在编译时可用。

解决方案

将依赖声明改为implementation即可解决问题：

implementation 'org.flywaydb:flyway-sqlserver'

implementation配置确保Flyway的SQL Server支持库会被包含在最终的应用包中，使得Flyway能够在运行时正确识别和操作SQL Server数据库。

技术原理

Flyway通过数据库驱动获取数据库版本信息后，会检查自身是否支持该版本。当缺少必要的数据库特定实现时（本例中的flyway-sqlserver），Flyway无法正确识别数据库类型和版本，从而抛出"Unsupported Database"异常。

Azure SQL Server 12.0虽然版本号较低，但实际上是完全受支持的。问题不在于版本兼容性，而在于运行时缺少必要的实现类。

最佳实践建议

1. 生产环境依赖管理：对于数据库驱动和数据库特定组件，应始终使用implementation而非compileOnly，确保运行时可用性。

2. 环境一致性验证：在升级过程中，应在尽可能接近生产环境的环境中验证变更，避免因环境差异导致的问题。

3. 依赖范围理解：

   • compileOnly：仅在编译时需要，不打包到最终产物
   • implementation：编译时需要且打包到最终产物
   • runtimeOnly：仅运行时需要，不参与编译

4. Flyway版本选择：虽然问题与Flyway版本无关，但仍建议使用较新版本以获得更好的功能和安全性。

总结

这个问题展示了开发环境与生产环境差异可能导致的隐蔽问题。通过正确配置Gradle依赖，特别是确保生产环境所需的依赖被正确打包，可以有效避免类似问题。对于数据库迁移工具如Flyway，确保数据库特定实现的可用性至关重要。