Keycloak中Liquibase无变更仍重复执行changeset问题求助

Liquibase重复执行renameColumn类型changeset的排查及解决方案 #

核心触发原因 #

Liquibase通过changeset id + author + changelog文件全路径组合的MD5值做执行校验，只要任意一项和DATABASECHANGELOG表中存储的历史记录不一致，就会判定为未执行的新变更，触发重复执行。

对应排查点和修复方案 #

• changelog路径校验不匹配
  自定义JPA Provider的changelog加载路径容易受Keycloak类加载逻辑、容器挂载配置影响，只要当前加载的changelog路径和首次执行时存入DATABASECHANGELOG表的FILENAME字段值不一致，就会触发重复执行。
  1. 先查询DATABASECHANGELOG表对应changeset记录的FILENAME字段值，对比当前changelog的实际加载路径是否一致
  2. 若路径不一致，可手动更新表中FILENAME字段为当前实际路径，或在changeset中配置ignoreClasspathPrefix="true"忽略路径前缀差异
• renameColumn配置缺失导致校验异常
  renameColumn类型的变更需要指定columnDataType属性，否则Liquibase每次执行时会从数据库读取列的元数据做比对，部分数据库（如MySQL、MariaDB）的元数据返回格式存在波动，会导致Liquibase误判changeset已修改，触发重复执行。
  补全changeset的columnDataType配置即可解决，示例如下：

  <changeSet id="your-rename-changeset-id" author="your-author-name">
    <renameColumn
      tableName="your_custom_table"
      oldColumnName="old_col_name"
      newColumnName="new_col_name"
      columnDataType="varchar(64)"
    />
  </changeSet>
  

• Docker动态挂载导致文件校验失败
  如果自定义Provider是通过容器volume动态挂载部署的，挂载时的文件修改时间、权限变动会导致Liquibase计算的changelog文件哈希值变动，触发校验失败。
  建议将自定义Provider直接打包到自定义Keycloak镜像中，避免动态挂载带来的文件属性变动问题。
• 临时规避方案
  如果需要快速恢复服务，可在对应changeset中添加前置条件，检测旧列存在时才执行变更，否则直接标记为已执行：

  <changeSet id="your-rename-changeset-id" author="your-author-name">
    <preConditions onFail="MARK_RAN">
      <columnExists tableName="your_custom_table" columnName="old_col_name"/>
    </preConditions>
    <renameColumn
      tableName="your_custom_table"
      oldColumnName="old_col_name"
      newColumnName="new_col_name"
      columnDataType="varchar(64)"
    />
  </changeSet>
  

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