使用Flyway将未纳管的现有PostgreSQL库迁移至新建空库的操作方法

Flyway没有和Liquibase generateChangelog 对标的内置反向生成脚本能力，本质是产品设计定位的差异：Flyway默认将迁移脚本作为所有库变更的唯一可信源头，不会主动做反向解析现有库生成脚本的逻辑。但完全可以通过组合工具实现等价效果，顺畅完成迁移和接入，具体步骤如下：

第一步：生成全量基线迁移脚本 #

借助PostgreSQL自带的pg_dump工具，从现有未托管库导出完整结构、数据、自定义对象，直接生成符合Flyway命名规范的基线脚本：

• 执行导出命令：

pg_dump \
  "现有数据库的完整连接串" \
  --no-owner \
  --no-privileges \
  --file=V1__baseline_existing_schema.sql

• 参数说明：
  • --no-owner、--no-privileges：导出的脚本不自带原库的属主、权限配置语句，避免和新空库的现有权限体系冲突
  • 导出文件必须严格按照Flyway脚本命名规则（V{版本号}__{脚本描述}.sql）命名，直接放入Flyway配置的迁移脚本目录下
• 导出校验：确认脚本内包含所有业务相关的表结构、索引、触发器、自定义函数、自定义类型、视图、数据库扩展（如uuid-ossp、pg_trgm）、全量业务数据，没有遗漏对象。

第二步：完成新空库的Flyway基线接入 #

根据迁移库的数据量大小，可选择两种等效的落地方式：

方式1（适合大体量库，迁移效率最高） #

• 先在新空库手动执行刚才生成的V1__baseline_existing_schema.sql，将新库的结构、数据灌入到和原库完全一致的状态
• 执行Flyway基线命令，让Flyway识别当前已有的库状态：

flyway baseline -baselineVersion=1

该命令会自动在新库中创建Flyway的历史追踪表（flyway_schema_history），插入一条版本号为1的已执行记录，标记当前库状态为基线版本，后续不会重复执行V1的全量脚本。

方式2（适合小体量库，操作最简） #

• 不需要手动执行基线脚本，直接将生成好的脚本放在Flyway迁移目录下，执行标准迁移命令：

flyway migrate

Flyway会自动在空库中执行全量基线脚本，同时在历史表中记录V1版本的执行痕迹，一次完成数据迁移+Flyway接入。

实操避坑要点 #

• 导出脚本时过滤掉CREATE DATABASE这类库级创建语句，避免和新空库的初始化流程冲突
• 提前配置好Flyway托管的schema范围（flyway.schemas参数），避免历史追踪表被创建到错误的schema下
• 脚本命名必须严格遵循规则：以V开头、接数字版本号、用两个下划线连接脚本描述，单下划线或符号错误都会导致Flyway无法识别脚本
• 如果后续需要将原库也纳入Flyway管理，只需要在原库执行一次flyway baseline -baselineVersion=1插入基线记录即可，后续所有新增变更统一通过V2、V3……版本的迁移脚本管理即可。

内容的提问来源于stack exchange，提问作者Sultan Zhumatayev