深入理解 Spring Boot 中的数据库迁移：Flyway 与 Liquibase 实战指南

文章目录

- 摘要
- [1. 引言：为什么需要数据库迁移？](#1. 引言：为什么需要数据库迁移？)
- - [1.1 传统数据库变更的痛点](#1.1 传统数据库变更的痛点)
  - [1.2 数据库迁移的核心价值](#1.2 数据库迁移的核心价值)
- [2. Spring Boot 对数据库迁移的支持](#2. Spring Boot 对数据库迁移的支持)
- [3. Flyway 实战详解](#3. Flyway 实战详解)
- - [3.1 核心概念](#3.1 核心概念)
  - [3.2 Spring Boot 集成](#3.2 Spring Boot 集成)
  - [3.3 编写迁移脚本](#3.3 编写迁移脚本)
  - [3.4 执行流程](#3.4 执行流程)
  - [3.5 回滚（Undo Migrations）](#3.5 回滚（Undo Migrations）)
- [4. Liquibase 实战详解](#4. Liquibase 实战详解)
- - [4.1 核心概念](#4.1 核心概念)
  - [4.2 Spring Boot 集成](#4.2 Spring Boot 集成)
  - [4.3 编写 Changelog](#4.3 编写 Changelog)
  - [4.4 回滚支持](#4.4 回滚支持)
- [5. Flyway vs Liquibase：深度对比](#5. Flyway vs Liquibase：深度对比)
- [6. 高级实践与最佳实践](#6. 高级实践与最佳实践)
- - [6.1 多环境配置](#6.1 多环境配置)
  - [6.2 CI/CD 集成](#6.2 CI/CD 集成)
  - [6.3 版本控制规范](#6.3 版本控制规范)
  - [6.4 监控与审计](#6.4 监控与审计)
- [7. 常见问题与排查](#7. 常见问题与排查)
- [8. 总结](#8. 总结)

摘要

在现代软件开发中，数据库结构（Schema）与应用程序代码一样，需要版本控制、协同演进和可重复部署。手动执行 SQL 脚本不仅效率低下，还极易出错，难以追踪变更历史。

为解决这一问题，数据库迁移工具（Database Migration Tools） 应运而生。Spring Boot 官方支持 Flyway 和 Liquibase 两大主流方案，它们能自动管理数据库版本、执行增量变更，并确保环境一致性。

本文将系统性地对比 Flyway 与 Liquibase 的设计理念、使用方式、优劣差异，并结合 Spring Boot 集成实战，涵盖初始化、回滚、多环境配置、CI/CD 集成等高级话题，帮助开发者构建可靠、可审计的数据变更流程。

1. 引言：为什么需要数据库迁移？

1.1 传统数据库变更的痛点

脚本散乱：SQL 文件分散在邮件、共享盘或个人电脑中。
顺序混乱：多人协作时，变更脚本执行顺序难以保证。
环境不一致：开发、测试、生产环境的数据库结构存在差异。
无法回滚：缺少可靠的回退机制，一旦出错修复困难。
缺乏审计：无法追溯"谁在何时修改了什么"。

1.2 数据库迁移的核心价值

数据库迁移 = 版本化的 Schema 变更 + 自动化执行 + 状态跟踪

通过将数据库变更视为"代码"，纳入版本控制系统（如 Git），实现：

可重复部署：任何环境均可从零重建最新结构
变更可追溯：每次变更都有记录和责任人
团队协作安全：避免冲突与覆盖
自动化集成：无缝嵌入 CI/CD 流水线

2. Spring Boot 对数据库迁移的支持

Spring Boot 通过 spring-boot-starter-data-jpa 或直接引入依赖，原生支持 Flyway 和 Liquibase。

功能	Flyway	Liquibase
配置方式	SQL 脚本为主	XML / YAML / JSON / SQL
回滚支持	有限（需手动编写 undo）	原生支持（自动生成或声明式）
学习曲线	简单直观	稍复杂，但更灵活
社区生态	成熟，企业广泛采用	功能强大，支持跨数据库抽象

选择建议：

追求简单、SQL 原生 → Flyway

需要跨数据库兼容、复杂回滚 → Liquibase

3. Flyway 实战详解

3.1 核心概念

Migration Version ：版本号（如 V1__init.sql）
Baseline：已有数据库的初始快照
Metadata Table ：flyway_schema_history，记录已执行的变更

3.2 Spring Boot 集成

添加依赖（Maven）：

xml 复制代码

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

注意：Spring Boot 3.x 默认使用 Flyway 9+，需匹配数据库驱动版本。

配置文件 （application.yml）：

yaml 复制代码

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/myapp
    username: user
    password: pass
  flyway:
    enabled: true
    baseline-on-migrate: true   # 若已有数据表，自动创建基线
    locations: classpath:db/migration
    encoding: UTF-8
    validate-on-migrate: true   # 执行前校验脚本一致性

3.3 编写迁移脚本

目录结构：

复制代码

src/main/resources/
└── db/
    └── migration/
        ├── V1__create_users_table.sql
        ├── V2__add_email_to_users.sql
        └── V3__create_orders_table.sql

示例脚本 （V1__create_users_table.sql）：

sql 复制代码

CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

命名规范：

V<version>__<description>.sql

版本号必须严格递增（支持小数如 V1_1__）

描述中空格用双下划线 __ 分隔

3.4 执行流程

应用启动时，Flyway 自动连接数据库
检查 flyway_schema_history 表是否存在
若不存在，创建该表并标记当前为"基线"
扫描 locations 下所有脚本，按版本号排序
执行未应用的脚本，并记录到元数据表

3.5 回滚（Undo Migrations）

Flyway 默认不支持自动回滚 ，但可通过 undo 脚本实现（需启用）：

sql 复制代码

-- U1__undo_create_users_table.sql
DROP TABLE users;

启用配置：

yaml 复制代码

spring:
  flyway:
    clean-disabled: false
    # 注意：undo 功能需 Flyway Teams 版本（商业版）

社区版限制 ：开源版 Flyway 不支持 undo，建议通过新版本脚本"正向修复"。

4. Liquibase 实战详解

4.1 核心概念

Changelog：变更日志文件（XML/YAML/JSON/SQL）
ChangeSet：最小变更单元，包含唯一 ID 和作者
DatabaseChangeLog Table ：DATABASECHANGELOG，记录已执行的 ChangeSet

4.2 Spring Boot 集成

添加依赖：

xml 复制代码

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

配置文件：

yaml 复制代码

spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.yaml
    contexts: production
    drop-first: false

4.3 编写 Changelog

主文件 （db.changelog-master.yaml）：

yaml 复制代码

databaseChangeLog:
  - include:
      file: db/changelog/changes/v1-create-users.yaml
  - include:
      file: db/changelog/changes/v2-add-email.yaml

变更集 （v1-create-users.yaml）：

yaml 复制代码

databaseChangeLog:
  - changeSet:
      id: 1
      author: liuyi
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: bigint
                  autoIncrement: true
                  constraints:
                    primaryKey: true
              - column:
                  name: name
                  type: varchar(100)
                  constraints:
                    nullable: false
              - column:
                  name: created_at
                  type: datetime
                  defaultValueComputed: CURRENT_TIMESTAMP

4.4 回滚支持

Liquibase 支持三种回滚方式：

自动生成（基于变更类型）：
bash 复制代码
```
liquibase rollbackCount 1
```

手动声明（在 ChangeSet 中定义）：

yaml 复制代码

- changeSet:
    id: 2
    author: liuyi
    changes:
      - addColumn:
          tableName: users
          columns:
            - column:
                name: email
                type: varchar(255)
    rollback:
      - dropColumn:
          tableName: users
          columnName: email

SQL 回滚脚本：

yaml 复制代码

rollback:
  - sqlFile:
      path: rollback/v2.sql

5. Flyway vs Liquibase：深度对比

维度	Flyway	Liquibase
核心理念	"SQL 即代码"	"声明式变更"
脚本格式	纯 SQL	多格式（推荐 YAML/XML）
学习成本	低，DBA 友好	中，需理解抽象模型
跨数据库兼容	弱（依赖 SQL 方言）	强（自动转换语法）
回滚能力	有限（需商业版）	原生支持
Diff 功能	需插件	内置（生成变更脚本）
社区活跃度	高	高
适用场景	简单项目、SQL 专家团队	复杂项目、多数据库环境

经验建议：

新项目且团队熟悉 SQL → Flyway

需支持 Oracle/MySQL/PostgreSQL 多端 → Liquibase

要求严格审计与回滚 → Liquibase

6. 高级实践与最佳实践

6.1 多环境配置

通过 Spring Profiles 区分环境：

yaml 复制代码

# application-dev.yml
spring:
  flyway:
    baseline-on-migrate: true

# application-prod.yml
spring:
  flyway:
    baseline-on-migrate: false  # 生产环境禁止自动基线
    validate-on-migrate: true

6.2 CI/CD 集成

在流水线中执行迁移（以 Flyway 为例）：

yaml 复制代码

# GitHub Actions 示例
- name: Run Flyway Migrations
  run: |
    docker run --rm -v $PWD/src/main/resources:/flyway/sql \
      flyway/flyway:9 \
      -url=jdbc:postgresql://db:5432/myapp \
      -user=dev \
      -password=secret \
      migrate

6.3 版本控制规范

所有迁移脚本纳入 Git
禁止修改已提交的脚本（会破坏 checksum）
使用语义化版本（如 V20250401_1__xxx.sql）

6.4 监控与审计

定期检查 flyway_schema_history 或 DATABASECHANGELOG 表
结合 Prometheus + Grafana 监控迁移状态
在变更脚本中添加注释说明业务背景

7. 常见问题与排查

问题	原因	解决方案
checksum validation failed	修改了已执行的脚本	使用 `flyway repair` 修复（谨慎！）
table already exists	重复执行 DDL	检查脚本是否幂等，或使用 `IF NOT EXISTS`
migration out of order	版本号跳跃	启用 `outOfOrder=true`（不推荐）或调整脚本顺序
Liquibase 找不到 changelog	路径错误	检查 `change-log` 配置是否正确

8. 总结

Flyway 与 Liquibase 是 Spring Boot 生态中数据库迁移的"双子星"。它们将数据库变更提升到与代码同等重要的地位，实现了 可重复、可审计、自动化 的数据演进流程。

关键结论：

不要手动改生产库：所有变更必须通过迁移脚本。
脚本即代码：纳入版本控制，Code Review。
选择适合团队的工具：Flyway 简洁，Liquibase 灵活。
回滚不是万能的：优先设计"向前兼容"的变更。
自动化是终极目标：让迁移成为部署的一部分。

掌握数据库迁移，是迈向专业级后端开发的重要一步。它不仅是技术实践，更是工程纪律的体现。

版权声明：本文为作者原创，转载请注明出处。