Flyway迁移中.sh脚本被忽略的问题分析与解决

问题背景

在使用Flyway进行数据库迁移时，用户遇到了一个典型问题：在包含.sql和.sh两种类型迁移脚本的情况下，只有.sql文件被正常执行，而.sh脚本被完全忽略。这种情况在使用Docker Compose部署的PostgreSQL 16.2环境中尤为明显。

环境配置分析

用户的配置采用了以下技术栈组合：

• Flyway OSS Edition 10.15.0
• PostgreSQL 16.2-alpine3.19镜像
• Windows 11操作系统
• Docker Compose编排

关键配置点包括：

1. 通过Docker卷将本地migrations目录挂载到容器的/flyway/sql路径
2. 使用filesystem作为迁移脚本位置
3. 设置了PostgreSQL连接参数和schema配置

问题现象

从日志中可以看到，Flyway成功验证并执行了18个.sql迁移脚本（从2到2.17版本），但完全忽略了同目录下的.sh脚本文件。这种选择性执行行为并非Flyway的默认设计，而是与配置参数相关。

根本原因

经过分析，问题出在Flyway的"SQL Migration Suffixes"（SQL迁移后缀）配置上。Flyway默认只识别特定后缀的迁移文件，而.sh不在默认支持的后缀列表中。这导致.sh脚本虽然存在于迁移目录中，但不会被Flyway识别为有效的迁移脚本。

解决方案

要解决这个问题，需要在Flyway配置中显式添加.sh后缀支持。具体可以通过以下两种方式实现：

1. 通过命令行参数： 在启动命令中添加-sqlMigrationSuffixes=.sql,.sh参数，明确告诉Flyway需要处理哪些后缀的文件。

2. 通过环境变量： 设置FLYWAY_SQL_MIGRATION_SUFFIXES环境变量，值为.sql,.sh。

对于Docker Compose部署，推荐采用第二种方式，在environment部分添加：

environment:
  FLYWAY_SQL_MIGRATION_SUFFIXES: ".sql,.sh"

最佳实践建议

1. 统一脚本类型：尽可能使用单一类型的迁移脚本（推荐.sql），减少维护复杂度。

2. 明确后缀配置：如果必须使用多种脚本类型，务必在配置中显式声明所有需要支持的后缀。

3. 脚本权限检查：对于.sh脚本，确保在容器内具有可执行权限。

4. 环境变量管理：将关键配置参数通过环境变量管理，提高配置的灵活性和可维护性。

5. 日志监控：定期检查Flyway执行日志，确认所有预期的迁移脚本都被正确处理。

总结

Flyway对迁移脚本的识别严格遵循配置规则，当遇到非标准后缀的脚本时，需要开发者明确告知Flyway应该处理哪些文件类型。通过合理配置SQL迁移后缀参数，可以灵活支持包括.sh在内的多种脚本类型，满足复杂的数据库迁移需求。