liquibase通过带id的原子changeset实现结构变更的可追溯、可重放与校验，避免人工同步导致的环境漂移；初始化需将现有库快照为基线并设logicalfilepath；大表加字段须分步（允许null→批量更新→设默认值→建索引）；执行失败后应基于databasechangelog和实际结构人工修复，禁用暴力清空。
为什么不能靠人工改表结构再同步SQL脚本
手动维护 ALTER TABLE 语句看似简单，实际在团队协作中极易出错：不同环境（dev/staging/prod）执行顺序不一致、漏跑某条语句、回滚逻辑缺失，导致结构漂移。Liquibase 的核心价值不是“多了一个工具”，而是把每次结构变更固化为带唯一ID的可追溯、可重放、可校验的原子操作。
它不依赖数据库当前状态做判断，而是通过对比 databasechangelog 表里的历史记录与本地变更文件，决定下一步该执行哪条 changeSet —— 这才是避免“线上表结构和文档对不上”的底层保障。
如何初始化一个Liquibase项目并接入现有MySQL库 初始化不是从空库开始，而是把当前生产库结构“快照”成第一个基线，否则后续所有迁移都会失败。
常见错误现象：liquibase.exception.CommandFailedException: Validation Failed: 1 changes have validation failures，本质是已有表被当成未声明的“脏数据”。
- 先用
liquibase snapshot或liquibase generate-changelog导出现有结构为changelog-initial.xml - 手动编辑该文件，在根
databaseChangeLog节点加属性：logicalFilePath="db/changelog/initial.xml"（用于去重识别） - 执行
liquibase update前，确保databasechangelog表为空，否则加参数--clear-checksums并确认无误 - 首次运行后，
databasechangelog表会写入一行，id为initial，author为admin，filename匹配你设的logicalFilePath
写一个安全的MySQL字段新增变更（含默认值与索引）
MySQL 对 ADD COLUMN 加默认值的行为在 5.7+ 和 8.0+ 差异极大：5.7 会锁全表，8.0 默认在线（但需确认 innodb_online_alter_log_max_size 足够）。Liquibase 不自动优化，得靠写法规避风险。
使用场景：给大表（>100万行）加非空字段，且要建索引。
- 永远分两步：先
addColumn允许 NULL，再addNotNullConstraint（如果真需要非空），避免单次锁表过久 - 默认值别写在
addColumn里，改用update+addDefaultValue组合，方便控制批量更新批次 - 索引必须单独写
createIndex，不要塞进addColumn；MySQL 不支持在 ADD COLUMN 时直接建索引 - 示例片段：
<changeset id="add-user-status" author="dev"><addcolumn tablename="user"><column name="status" type="TINYINT"></column></addcolumn><update tablename="user"><column name="status" value="1"></column></update><adddefaultvalue columnname="status" columndatatype="TINYINT" defaultvaluenumeric="1" tablename="user"></adddefaultvalue><createindex indexname="idx_user_status" tablename="user"><column name="status"></column></createindex></changeset>
如何处理Liquibase执行失败后的状态修复liquibase update 卡住或报错后，最危险的操作是删掉 databasechangelog 表重来 —— MySQL 可能已部分执行了 DDL（比如字段加了一半），但记录没写入，下次又会重复执行，直接报 duplicate column。
关键判断依据只有两个：databasechangelog 表内容 + 当前数据库真实结构。
- 查
SELECT * FROM databasechangelog WHERE MD5SUM IS NULL：这类记录代表执行中断，需人工核对是否真没生效 - 查
SELECT COUNT(*) FROM information_schema.COLUMNS WHERE TABLE_NAME = 'xxx' AND COLUMN_NAME = 'yyy'，确认字段是否存在 - 若已存在但没记入
databasechangelog，用liquibase mark-next-change-set-ran跳过这条（别删记录） - 若没存在但记录已写入，用
DELETE FROM databasechangelog WHERE id = 'xxx'回退记录，再重试 - 永远别在生产环境用
--force或--clear-checksums，除非你刚核对完 checksum 和实际 SQL 内容完全一致
Liquibase 的复杂点不在语法，而在于它强制你直面“结构变更也是代码”这件事：每条 changeSet 必须幂等、可逆、带上下文注释，且所有环境共享同一份 changelog 文件树。很多人卡在第一步不是不会写 XML，是没想清楚“这个字段加在哪个版本之后才合理”。
