4. Flyway 支持的数据库：列表与驱动配置要点

Flyway 作为一款数据库迁移工具，其核心优势之一在于对主流关系型数据库的广泛支持。理解 Flyway 所支持的数据库列表以及各数据库驱动的配置要点，是进行跨环境迁移架构设计的基础。本章将系统梳理 Flyway 支持的数据库生态，并针对最常用的四种数据库（MySQL、PostgreSQL、Oracle、SQL Server）给出驱动配置的详细指南。

4.1 支持的数据库总览

Flyway 通过社区版和团队版（Teams/Enterprise）提供对不同数据库的支持。社区版覆盖了绝大多数开源和商业数据库，而团队版则增加了对更多商业数据库及高级特性的支持。下表列出了 Flyway 支持的主要数据库及其版本要求：

数据库 最低支持版本 Flyway 版本要求 备注
MySQL 5.6 社区版 支持 MySQL 8.0+ 的窗口函数等新特性
MariaDB 10.2 社区版 与 MySQL 驱动兼容，推荐使用专用驱动
PostgreSQL 9.6 社区版 支持 PG 15+ 的逻辑复制槽等高级功能
Oracle 11g 社区版 需手动下载 ojdbc 驱动，注意许可证
SQL Server 2012 社区版 支持 Azure SQL Database 和 SQL Server 2019+
DB2 10.5 团队版 需要 IBM 官方 JDBC 驱动
SQLite 3.25 社区版 仅用于开发/测试，不支持并发写
H2 2.1 社区版 常用于单元测试和嵌入式场景
Redshift 1.0 团队版 基于 PostgreSQL 协议，但功能受限
Snowflake 6.0 团队版 云原生数仓，需专用驱动
架构提示： 在选择数据库时，建议优先使用 Flyway 社区版支持的数据库（如 MySQL、PostgreSQL、Oracle、SQL Server），以便在开源许可下获得完整的迁移能力。对于团队版专属数据库（如 DB2、Redshift），需评估许可证成本与团队规模。

4.2 数据库驱动配置要点

Flyway 通过 JDBC 驱动与数据库通信。正确配置驱动是迁移成功的第一步。以下针对四种主流数据库，分别说明驱动下载、类名、连接 URL 格式及常见配置陷阱。

4.2.1 MySQL / MariaDB

MySQL 驱动配置相对简单，但需注意驱动版本与数据库版本的兼容性。从 MySQL 8.0 开始，官方推荐使用 com.mysql.cj.jdbc.Driver。

  • 驱动 JAR： mysql-connector-java（或 mysql-connector-j）
  • 驱动类名： com.mysql.cj.jdbc.Driver
  • 连接 URL 格式：
jdbc:mysql://<host>:<port>/<database>?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
  • 配置要点：
    • useSSL=false：开发环境建议关闭 SSL 以减少延迟；生产环境应启用并配置证书。
    • allowPublicKeyRetrieval=true：MySQL 8.0+ 默认使用 caching_sha2_password 插件，需显式允许公钥检索。
    • serverTimezone=UTC：避免时区转换导致的日期错误。
    • Flyway 配置示例（flyway.conf）：
flyway.url=jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC
flyway.user=root
flyway.password=secret
flyway.driver=com.mysql.cj.jdbc.Driver

4.2.2 PostgreSQL

PostgreSQL 驱动（org.postgresql.Driver）是 Flyway 社区版中兼容性最好的驱动之一，支持几乎所有 PostgreSQL 特性。

  • 驱动 JAR： postgresql（或 postgresql-jdbc）
  • 驱动类名： org.postgresql.Driver
  • 连接 URL 格式：
jdbc:postgresql://<host>:<port>/<database>?currentSchema=public&ApplicationName=Flyway
  • 配置要点：
    • currentSchema：指定默认 schema，避免迁移脚本中频繁使用 schema 前缀。
    • ApplicationName：设置应用名称，便于在数据库监控中识别 Flyway 连接。
    • PostgreSQL 支持 PGPASSWORD 环境变量，但 Flyway 配置中仍建议使用 flyway.password。
    • Flyway 配置示例：
flyway.url=jdbc:postgresql://localhost:5432/mydb?currentSchema=app_schema
flyway.user=app_user
flyway.password=app_pass
flyway.driver=org.postgresql.Driver

4.2.3 Oracle

Oracle 驱动配置相对复杂，主要因为 Oracle JDBC 驱动（ojdbc）的版本选择与许可证问题。Flyway 社区版支持 Oracle 11g 及以上版本。

  • 驱动 JAR： ojdbc8（对应 Oracle 12c/19c）或 ojdbc10（对应 Oracle 21c+）
  • 驱动类名： oracle.jdbc.OracleDriver
  • 连接 URL 格式：
jdbc:oracle:thin:@//<host>:<port>/<service_name>
  • 配置要点：
    • 使用 Thin 驱动（@// 格式），避免使用 OCI 驱动（需要安装 Oracle 客户端）。
    • Oracle 12c+ 引入了 CDB/PDB 架构，连接 URL 中的 service_name 应指向 PDB 服务名。
    • 驱动 JAR 需手动下载并放置在 Flyway 的 drivers 目录下，或通过 Maven/Gradle 依赖管理。
    • Flyway 配置示例：
flyway.url=jdbc:oracle:thin:@//oracle-host:1521/ORCLPDB1
flyway.user=flyway_user
flyway.password=flyway_pass
flyway.driver=oracle.jdbc.OracleDriver
许可证警告： Oracle JDBC 驱动受 Oracle 二进制许可协议约束。在商业环境中使用前，请确保已获得 Oracle 的授权。Flyway 社区版不包含 Oracle 驱动，需自行下载。

4.2.4 SQL Server

SQL Server 驱动配置需注意驱动版本与 SQL Server 版本的匹配。Microsoft 官方提供了 mssql-jdbc 驱动，支持 SQL Server 2012 至 2022 以及 Azure SQL Database。

  • 驱动 JAR： mssql-jdbc
  • 驱动类名： com.microsoft.sqlserver.jdbc.SQLServerDriver
  • 连接 URL 格式：
jdbc:sqlserver://<host>:<port>;databaseName=<database>;encrypt=true;trustServerCertificate=false
  • 配置要点：
    • encrypt=true：生产环境建议启用 TLS 加密；开发环境可设为 false。
    • trustServerCertificate=false：生产环境应验证服务器证书；开发环境可设为 true 以跳过验证。
    • SQL Server 支持 Windows 集成身份验证，但 Flyway 通常使用 SQL Server 身份验证（用户名/密码）。
    • Flyway 配置示例：
flyway.url=jdbc:sqlserver://localhost:1433;databaseName=mydb;encrypt=false
flyway.user=sa
flyway.password=Strong!Pass
flyway.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver

4.3 驱动配置架构图

下图展示了 Flyway 与四种主流数据库之间的驱动连接架构，以及各驱动在迁移流程中的位置：

Flyway 数据库驱动连接架构 Flyway 数据库驱动连接架构 Flyway 迁移引擎 JDBC 驱动层 MySQL mysql-connector-java PostgreSQL postgresql-jdbc Oracle ojdbc8/ojdbc10 SQL Server mssql-jdbc 各驱动配置核心要点 • MySQL：useSSL、allowPublicKeyRetrieval、serverTimezone • PostgreSQL：currentSchema、ApplicationName • Oracle：Thin 驱动、PDB 服务名、手动下载驱动 JAR • SQL Server：encrypt、trustServerCertificate、集成身份验证

4.4 驱动配置常见问题与避坑指南

在实际项目中，驱动配置错误是导致 Flyway 迁移失败的最常见原因之一。以下列出各数据库驱动配置的典型问题及解决方案：

MySQL 常见问题：
  • Public Key Retrieval 错误： 报错 Public Key Retrieval is not allowed。解决方案：在连接 URL 中添加 allowPublicKeyRetrieval=true。
  • SSL 连接超时： 开发环境建议设置 useSSL=false，或配置正确的 SSL 证书。
  • 时区异常： 报错 The server time zone value 'XXX' is unrecognized。解决方案：设置 serverTimezone=UTC 或 Asia/Shanghai。
PostgreSQL 常见问题：
  • Schema 未找到： 迁移脚本中引用了不存在的 schema。解决方案：在连接 URL 中设置 currentSchema，或使用 flyway.schemas 配置项。
  • 密码包含特殊字符： 密码中的 @、:、/ 等字符需进行 URL 编码（如 %40 代替 @）。
  • 连接池耗尽： 高并发迁移时，确保 PostgreSQL 的 max_connections 参数足够。
Oracle 常见问题：
  • 驱动版本不匹配： 使用 ojdbc8 连接 Oracle 11g 可能导致兼容性问题。建议根据 Oracle 版本选择对应驱动。
  • 服务名错误： 使用 SID 格式（jdbc:oracle:thin:@host:port:SID）而非服务名格式，导致连接失败。推荐使用服务名格式 @//host:port/service_name。
  • 权限不足： Flyway 用户需要 CREATE SESSION、CREATE TABLE、CREATE SEQUENCE 等权限。
SQL Server 常见问题：
  • TLS 握手失败： 低版本 SQL Server 不支持 TLS 1.2。解决方案：设置 encrypt=false 或升级 SQL Server。
  • 集成身份验证配置复杂： 使用 SQL Server 身份验证（用户名/密码）可简化配置。
  • 数据库名称大小写敏感： SQL Server 默认不区分大小写，但 Azure SQL Database 可能区分。建议统一使用小写。

4.5 驱动配置最佳实践

基于上述配置要点和常见问题，总结以下驱动配置的最佳实践：

  1. 统一驱动版本： 在团队中统一使用相同版本的 JDBC 驱动，避免因驱动版本差异导致的兼容性问题。
  2. 使用连接池（可选）： 对于高并发迁移场景，可考虑使用 HikariCP 等连接池管理 JDBC 连接，但需注意 Flyway 默认使用自己的连接管理。
  3. 配置外部化： 将数据库连接信息（URL、用户名、密码）放在环境变量或配置中心，避免硬编码在 Flyway 配置文件中。
  4. 测试驱动配置： 在 CI/CD 流水线中增加驱动连接测试步骤，确保迁移前数据库可达。
  5. 记录驱动日志： 启用 Flyway 的调试日志（flyway.log=debug），便于排查驱动连接问题。
架构建议： 在多环境部署中，建议为每个环境（开发、测试、预发布、生产）维护独立的 Flyway 配置文件，其中驱动配置（如 SSL、时区）可根据环境安全要求进行调整。例如，开发环境可关闭 SSL 和证书验证，生产环境则必须启用。
← 上一章 📖 返回目录 下一章 →