Liquibase XML转YAML变更日志后报"relation already exists"错误求助

这种情况真的很让人头大——明明看着变更内容完全一致，换个YAML格式就报「表已存在」的错误，切回XML又一切正常，肯定摸不着头脑对吧？我来帮你拆解下可能的原因，以及对应的排查方向：

1. 变更集的唯一标识不匹配（最常见原因） #

Liquibase是通过变更集的id、author、所在文件路径这三个字段来判断某个变更是否已经执行过的。如果YAML里的这三个信息和XML版本不一致，哪怕内容完全一样，Liquibase都会把它当成全新的变更集重复执行，自然就会报「表已存在」的错误。

要排查这个：

• 检查YAML里的id是否是字符串类型：XML里的id是字符串（比如<changeSet id="1" author="marc3l">），YAML里如果写id: 1，会被解析成数字，和数据库DATABASECHANGELOG表里存的字符串"1"不匹配，导致重复执行。这时候要改成id: "1"（加引号）。
• 核对author的拼写、大小写是否和XML完全一致，比如XML是author="Marc3l"，YAML写成author: "marc3l"，也会被当成不同的变更集。
• 检查主变更日志里引用子文件的路径，XML里的<include file="changes/v1.xml"/>和YAML里的- include: { file: changes/v1.yaml }，路径的大小写、文件名后缀是否正确，有没有多写或少写目录层级。

2. YAML的语法/缩进错误 #

YAML对缩进和格式的要求比XML严格得多，一点点错误就可能导致Liquibase解析异常：

• 用了tab键缩进而不是空格（YAML只允许空格）
• 变更集内部的层级缩进不对，比如createTable的属性没有和changes下的列表项对齐：

  # 错误示例：tableName缩进错误，Liquibase无法识别createTable的完整配置
  - changeSet:
      id: "1"
      author: "marc3l"
      changes:
        - createTable:
      tableName: users 
  

  正确的缩进应该是每个子层级比父层级多2个或4个空格，保持统一即可。

可以用liquibase validate命令来验证YAML的语法合法性，这个命令会直接指出格式错误或无效属性。

3. YAML解析的隐式类型或属性差异 #

有些情况下，XML和YAML对同一属性的解析逻辑略有不同：

• 比如包含特殊字符的表名、列名，XML里不需要加引号，但YAML里必须用引号包裹，否则会解析失败。
• 某些旧版本的Liquibase对YAML的支持有bug，比如特定变更类型（比如addColumn、createIndex）的属性在YAML里的命名或解析方式和XML不一致。这种情况下可以尝试升级到最新的稳定版本Liquibase，看看问题是否消失。

4. 主变更日志的引用逻辑差异 #

如果你的主变更日志是多个子文件的集合，要检查XML和YAML版本的引用顺序、是否有重复引用：

• 比如XML里按顺序引用了A、B、C三个变更文件，YAML里不小心重复引用了A，就会导致A里的创建表操作执行两次，报错表已存在。
• 检查YAML里的include指令是否正确，比如有没有漏写relativeToChangelogFile: true（如果用相对路径的话），导致Liquibase找不到文件，跳过某些变更集或重复加载。

如果暂时赶时间，切回XML肯定能快速恢复正常，但其实只要排查出上面的某一个问题，YAML格式是完全可以正常工作的——毕竟YAML的优势就是更简洁易读。建议先花10分钟用liquibase validate检查语法，再对比数据库里的DATABASECHANGELOG表，看看XML执行后的条目和YAML试图执行的条目有什么差异，大概率能找到问题所在。

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