Liquibase preConditions 实战：数据库变更的智能判断与避坑

我接手的很多数据库项目第一件事不是看表结构而是先翻Liquibase的changelog写得干不干净。Liquibase的数据库版本管理能力确实强但有块功能经常被团队忽略就是preConditions——执行前判断。它能让一个变更集在真正执行SQL之前先到目标数据库里探一探底表在不在、列在不在、当前连接的是不是某类数据库、某条SQL查询的返回值是否符合预期。只有条件满足才继续执行不满足则按预设策略跳过、标记为已执行或者把整个更新流程停住。这篇文章我会把preConditions的常见类型、配置方式、失败策略选择以及我在生产环境里实际踩过的坑都展开讲一遍。适合正在维护一套需要同时跑多种数据库的changelog、需要经常做增量数据修复、或者想把数据库变更的“人肉判断”变成“代码判断”的读者。下面直接进入正题。1. 为什么需要 preConditions从一个真实场景说起1.1 没有 preConditions 时的“土办法”前两年我接手过一个迁移项目业务同时跑在Oracle和MySQL两套库上公司要求同一套代码、同一套Liquibase changelog管理两边。听起来不难但第一个星期就出问题了有个变更集为了优化查询给用户表加了一个MySQL特有的函数索引写法Oracle直接报语法错误。当时团队的处理方式让我印象深刻他们维护了两份changelog一份MySQL版、一份Oracle版每次改表结构都要同步改两份文件改完还要人工确认两边的changeSet没有漂移。后来又换成了shell脚本在跑Liquibase之前先连数据库查db_type然后决定选择哪个changelog文件。这确实能跑通但是脚本逻辑散落在Jenkins任务里新同事接手时根本不知道有这层判断而且一旦脚本和changelog不同步上线时就只能干瞪眼。其实这个问题Liquibase自己就有标准解法在变更集之前加一段preConditions让变更本身对自己要运行的数据库环境做校验。Liquibase帮我们把“探路”和“执行”绑在同一个描述文件里同一个评审流程审掉任何环境跑了同一份文件都是同样的逻辑不用再靠外部脚本兜底。1.2 preConditions 不是 context也不是 labels很多团队分不清preConditions和context、labels的区别我刚开始也混淆过。context和labels是“运行参数控制”执行Liquibase时传入--contextsdev那么带有contextdev的变更集会执行其余跳过。这相当于出门前看天气预报说今天要下雨那就不带伞直接换地铁。preConditions则是“数据库事实控制”它不看外部参数而是真的连到数据库里去查表、查列、查系统视图。如果数据库现状不满足条件就按配置处理。这相当于人都走到公园门口了摸口袋发现没带钥匙于是决定回家。两个维度可以配合使用但不能互相替代。比如context适合控制不同环境跑不同数据初始化脚本而preConditions更适合控制“这个表的这个列已经被手工加过了所以加列变更集应该跳过”。一个是计划层面的筛选一个是事实层面的校验。控制维度看什么典型场景失败处理context / labels外部运行参数开发库跑测试数据生产库不跑不满足直接不进入preConditions目标数据库实际状态表已存在则跳过建表不存在才创建按onFail策略处理两者结合参数数据库状态生产环境且列不存在时才加列双重保险2. preConditions 的类型全景与选型标准Liquibase官方的preConditions标签底下可选的判断类型很多但实际生产里真正高频用的就几类。我会按“环境类、对象存在类、SQL自定义类、组合类”四组来讲方便你选型。2.1 环境与运行身份类判断环境判断里最常用的是dbms也就是判断当前连接的数据库类型。写法很直接changeSet idadd_nickname_column authorzhangsan preConditions onFailWARN dbms typemysql/ /preConditions sql ALTER TABLE user ADD COLUMN nickname varchar(50) AFTER name; /sql /changeSet这个例子是给MySQL独有写法加的保护如果是MySQLpreConditions通过执行后面的SQL如果不是MySQL就会走onFail对应逻辑。dbms的类型值支持逗号分隔比如typemysql,postgresql也支持取反写法type!oracle表示“只要不是Oracle就通过”。另一个环境判断是runningAs判断当前执行Liquibase的数据库用户是不是指定用户。比如某些高危变更要求必须用只读账号执行或者必须用特权账号执行可以直接判断preConditions onFailHALT runningAs typedeploy_user/ /preConditions还有changeLogPropertyDefined判断外部传入的changelog参数有没有定义。这个在拼接schema名、文件名时很实用避免因为漏传参数导致SQL变成ALTER TABLE ${schema}.user这种带着变量名执行的错误。2.2 数据库对象存在性判断对象存在性判断是日常用得最多的一类也是最符合“幂等变更”思路的一组。常用类型有tableExists、columnExists、indexExists、sequenceExists、viewExists、foreignKeyConstraintExists、primaryKeyExists。它们都有带有schemaName、tableName之类的属性用来精确指定要检查的对象。举个例子某个环境里用户表user已经被运维手工加过email列但changelog是后来才引入的里面有个加列变更集第一次跑就会报“column already exists”。用columnExists就能把这种情况化解changeSet idadd_email_to_user authorlisi preConditions onFailMARK_RAN not columnExists schemaName${schema} tableNameuser columnNameemail/ /not /preConditions addColumn tableNameuser column nameemail typevarchar(100)/ /addColumn /changeSet这段逻辑是“如果user.email列不存在才执行加列如果列已经存在就跳过并把变更集标记成已执行”。实际效果是无论底层库处于什么状态这一条变更集都能安全跑完不会因为重复执行报错。这类判断的选型原则很简单要动哪个对象的哪个方面就优先检查对应对象是否存在。比如建索引前检查indexExists建外键前检查foreignKeyConstraintExists删列前检查columnExists避免SQL把不存在的对象删掉导致库锁等待或报错。2.3 sqlCheck用一条SQL定制判断标准当内置标签解决不了问题的时候sqlCheck是最后的兜底手段。它允许你自己写一条SELECT语句Liquibase执行后拿结果和expectedResult属性做比较相等则条件通过不相等则失败。preConditions onFailHALT sqlCheck expectedResult1 SELECT COUNT(*) FROM information_schema.tables WHERE table_schema DATABASE() AND table_name user /sqlCheck /preConditions这个示例检查MySQL的information_schema里是否存在user表。你可以把它理解为一种“自定义探针SQL”内置条件管不着的比如要判断某个业务表里有没有满足某个状态的数据、某个序列的当前值是否达到阈值、某个视图的定义是否已经升级过都可以用它来实现。sqlCheck非常灵活但必须保证查询返回的结果是“一行一列”。如果返回多行或者返回多列Liquibase会直接当成判断失败。这也是它最容易踩坑的地方后面我会专门展开讲。2.4 组合逻辑与全局/局部放置位置单个preConditions可能不够用所以Liquibase提供了三个组合逻辑标签and、or、not。语义和编程里的与、或、非一致。例如preConditions onFailHALT or dbms typemysql/ dbms typepostgresql/ /or /preConditions这段的含义是“只要是MySQL或PostgreSQL就认为条件满足若是其他数据库则失败”。and则是所有子条件同时满足才通过not是取反结果。另一个关键点preConditions可以放在两个不同位置。放在databaseChangeLog顶层属于全局preConditions会影响整个changelog文件放在某个changeSet内部则只影响那一个变更集。全局判断适合做“硬门槛”比如要求必须以指定数据库类型运行整份变更否则直接不执行局部判断适合做“单点保护”比如某个变更集只允许在某个环境下执行。3. 实操搭一套可控的执行前判断流程3.1 先决定失败策略onFail 和 onError 怎么选preConditions标签上有两个主要策略属性onFail和onError。前者是“判断结果为失败”时怎么处理后者是“执行判断过程本身出错”时怎么处理。两者默认值都是HALT但实际项目里我很少用默认值。策略值行为表现适用场景HALT停止当前变更集并终止后续所有变更集执行前置条件不满足后续变更都不该跑CONTINUE跳过当前变更集继续执行后续变更集某个对象在当前库不存在其余照常执行MARK_RAN跳过当前变更集并在databasechangelog中标记该变更集已执行已手工完成的变更以后不再重复判断WARN打印警告然后继续执行当前变更集条件不满足只是提醒变更仍需执行这里我刚接触时理解错了两个地方。第一个是CONTINUE和MARK_RAN的区别CONTINUE只是“这次跳过不记录已执行”下次再跑changelog时还会重新判断MARK_RAN会真的把这个changeSet写入执行记录下次不会再管它。第二个是WARN它不会跳过变更集而是“警告一下照样执行”所以如果你本意是“条件不满足就跳过”千万别用WARN用了会导致原本不想跑的SQL照样跑。onError日常用得不多但有一种情况很典型sqlCheck里的SQL本身写错了或者当前连接账号没有查某个系统视图的权限Liquibase会抛异常而不是返回false。此时可以设onErrorCONTINUE来避免一个次要检查把整体流程搞挂。3.2 跨数据库兼容一个 dbms 判断的完整示例回到开头的双库场景我当时的处理方式是把整个changelog按变更集拆分每个变更集用dbms preConditions明确它只适用哪类数据库。比如下面这段就是MySQL的索引优化语句changeSet idoptimize_user_index_mysql authorzhangsan preConditions onFailCONTINUE dbms typemysql/ /preConditions sql ALTER TABLE user ADD INDEX idx_user_email (email(32)); /sql /changeSet注意这里我特意写了onFailCONTINUE而不是默认的HALT。原因是如果当前数据库不是MySQL这个变更集只是不需要执行而已绝不希望Liquibase因为这个条件不满足把整个changelog后面的所有变更都停掉。这是跨库项目最容易翻车的点——很多人只在preConditions里写了dbms typemysql/没有显式指定onFail结果Oracle上一跑后续变更全被HALT掉看起来像是数据库崩溃了实际上是默认策略在起作用。我的建议是除非你真的想“不满足就直接终止所有变更”否则每个局部preConditions都要显式写策略。把默认值当成“显式声明”的底线而不是依赖它。3.3 数据修复幂等columnExists not MARK_RAN 实战数据修复场景里我最推荐的是columnExists带not再配MARK_RAN。这套组合在线上跑增量修复时非常稳。有一次生产库的payment表缺少一个refund_status列DBA手工加了列但团队随后才把加列变更集补进changelog。如果我们直接把这个变更集提交上线由于没有preConditions保护Liquibase会再执行一次ALTER TABLE ADD COLUMN数据库直接报列已存在错误。有了以下写法就不会有问题changeSet idadd_refund_status_column authordba preConditions onFailMARK_RAN not columnExists schemaNamepublic tableNamepayment columnNamerefund_status/ /not /preConditions addColumn tableNamepayment column namerefund_status typevarchar(20) defaultValueINIT/ /addColumn /changeSet当Liquibase跑到这条变更集时先检查列是不是不存在。如果列不存在说明确实需要执行加列操作那not取反后条件成立正常加列并记录执行。如果列已经存在not取反后条件不成立onFailMARK_RAN会把这条变更集标记为已执行跳过实际的加列动作。最终效果就是不管数据库处于哪种状态这条变更集都能安全地“收敛”到最终状态并且不会被重复执行。这种思路可以推广到建表、建索引、加约束等各种场景。生产环境里“手工补过一次线上结构”这种事根本避免不了changelog要能兼容这种事实而不是一遇到状态已满足就崩溃。3.4 sqlCheck 的返回值坑与稳定写法sqlCheck灵活但坑也最多。最常见的坑是返回结果不是“一行一列”以及返回值类型不匹配。先看行数和列数。下面的写法就是错的SELECT id FROM user WHERE status ACTIVE;如果表里有3条满足条件的数据返回3行Liquibase报错“precondition returned more than one row”如果一条都没有返回0行报错“precondition did not return any rows”。正确写法必须把结果聚合到一行一列SELECT COUNT(*) FROM user WHERE status ACTIVE;再看值类型。expectedResult1在XML里是字符串Liquibase会把查询结果转成字符串后和它比较所以COUNT(*)返回的1没有问题。但有些数据库返回布尔类型比如SELECT EXISTS (...)MySQL会返回0或1PostgreSQL会返回true或false。这时候expectedResult1就可能对不上。我的习惯是任何sqlCheck都统一用COUNT(*)或者CASE WHEN ... THEN 1 ELSE 0 END来保证返回数值型结果不碰布尔类型。还有一个小坑sqlCheck里的SQL语句不要以分号结尾。部分数据库驱动对分号处理不一致Liquibase解析时可能把分号当成SQL的一部分导致执行报语法错误。我在PostgreSQL上踩过一次去掉分号后一切正常。3.5 事务、锁定与 updateSQL 模式下的注意事项Liquibase在普通update命令下会先获取DATABASECHANGELOGLOCK锁再去逐个执行变更集。带preConditions的变更集会先执行判断判断通过后执行变更。如果判断不通过且策略是HALT整个命令终止后续变更不执行。但有一个容易被忽略的点Liquibase获取的锁要等命令结束才释放。如果preConditions里的SQL特别慢比如你写了一条全表扫描业务表的查询锁的持有时间就会被拖长多实例并发部署时其他节点只能等着看起来就像“卡死”。所以preConditions里的SQL一定要轻量。能用系统视图解决的就不要查业务表比如判断对象是否存在优先用information_schema或对应数据库的元数据视图。这既是性能问题也是并发安全的问题。另外用updateSQL命令生成SQL脚本时preConditions默认也会执行。但“生成脚本的机器”和“真正执行脚本的数据库”往往不是同一个环境可能本地是开发库判断条件通过了脚本拿到生产库执行时却完全不适用。这时候可以在preConditions上显式加onSqlOutputIGNORE让Liquibase在生成SQL脚本时跳过判断把判断留给人工或执行方preConditions onSqlOutputIGNORE onFailHALT dbms typemysql/ /preConditions这个属性默认值是TEST即照常执行判断。如果你的团队有“本地生成SQL、线下评审、线上执行”的流程记得把onSqlOutputIGNORE加在高危或者强环境相关的判断上。4. 常见问题与排查技巧实录4.1 判断条件“没生效”或误报失败先看这三点遇到过几次“preConditions明明写了但行为和预期不一样”的工单。排查下来基本三个原因。第一preConditions放错了位置。放在changeSet里叫局部判断只影响当前变更集放在databaseChangeLog开头叫全局判断会影响整个文件。如果你期望“某条不满足就跳过当前一条”结果写成了全局判断那当然会是“其他变更也被影响”的表现。反过来也一样。第二onFail策略没按预期理解。比如用了WARN以为“不满足就跳过”实际WARN是“警告且继续执行”。这种理解偏差会导致该执行的没执行不该执行的执行了。第三局部preConditions忘了写子条件。我在代码评审里见过不少changeSet idtest authorsomeone preConditions onFailMARK_RAN tableExists tableNameuser/ /preConditions createTable tableNameuser/ /changeSet这里的本意可能是“表不存在才建表”但tableExists检查的是“表存在”逻辑正好写反了。建表操作应该用not包一层像这样preConditions onFailMARK_RAN not tableExists tableNameuser/ /not /preConditions条件逻辑拧反是preConditions最常见的隐形bug代码评审阶段要逐条对着英文语义读一遍。4.2 sqlCheck 结果行数、列数与值类型匹配sqlCheck出的问题绝大多数集中在返回结构和值类型上。我做一个速查表给你参考问题表现原因解决办法报错did not return any rowsSELECT结果为空改成COUNT(*)聚合报错returned more than one rowSELECT返回多行加聚合函数或LIMIT 1报错returned more than one columnSELECT返回多列只保留一列expectedResult对不上数据库返回布尔或字符串统一用1/0数值格式语法错误SQL带分号结尾去掉末尾分号排查时最快的办法是先把sqlCheck里的SQL复制到数据库客户端里跑一遍看返回几行几列、值长什么样再对照expectedResult逐字核对。很多误报是PostgreSQL返回true、Oracle返回1这类数据库差异造成的。4.3 schemaName 与大小写查不到对象的第一嫌疑tableExists、columnExists这类判断如果一直返回false但表明明就在库里先别怀疑Liquibase坏了九成是schemaName或大小写问题。Connections默认schema在不同数据库里行为不一样。PostgreSQL默认是public但如果连接用户改了search_path不指定schema时可能查的不是你以为的那个schema。Oracle则是大小写敏感如果建表时用的双引号把小写表名写成了user而你判断时写tableNameUSER自然查不到。我的建议是能显式写schemaName就显式写不要依赖连接默认。例如tableExists schemaNamepublic tableNameuser/参数化写法也可以配合property比如schemaName${schema}这样环境切换时只需要替换参数。生产排障时如果判断总是失败先把判断里写的schemaName、tableName原样拿到数据库客户端执行一遍确认对象确实存在、名字完全一致再回头查Liquibase配置。4.4 onFailHALT 把整份 changelog 停住后的救援流程这是生产事故里最常见的场景某个局部preConditions没写策略默认HALT条件不满足导致整份changelog后面的变更全部没执行。表现就是日志里出现类似“precondition failed”的信息DATABASECHANGELOG表里只记录了一部分变更集。遇到这种情况先不要急着重新跑整个update。第一步打开日志定位是哪一条preConditions失败看清楚判断的是什么对象第二步判断当前数据库状态和判断条件是否确实不一致是误报还是真不满足第三步如果只是策略问题比如这个变更集本来就不是给当前库用的就把onFail改成CONTINUE或MARK_RAN重新跑。这里有一个关键习惯重新跑之前先检查DATABASECHANGELOG表里已经插入了哪些变更集记录。因为Liquibase是通过这张表做断点续跑的已经成功执行的变更集不会重复执行所以你只需要关心“停在中间”的那一条以及它后面的变更。手动删记录是非常危险的操作能不动就不动绝大多数情况下修正preConditions策略后重跑即可。4.5 多实例并发时的锁与慢查询提醒当多个应用实例同时启动、同时执行Liquibase时DATABASECHANGELOGLOCK只能被一个实例拿到其他实例都在等待。如果preConditions里放了慢SQL锁的持有时间会被拉长后面的实例等待时间呈线性上涨极端情况下会触发应用启动超时。所以preConditions里的SQL要遵循“系统视图优先、业务表禁止”的原则。只是判断对象存在性就老老实实用information_schema或者pg_catalog这类系统元数据确实需要判断业务数据状态也尽量写成SELECT COUNT(*) WHERE ...配合索引保证毫秒级返回。另外把preConditions和真正的变更集SQL放在一个changelog文件里评审时注意一下判断代价别让一个判断逻辑变成整个发布的瓶颈。4.6 团队规范怎么定如果团队用Liquibase做统一变更管理我建议把preConditions的用法沉淀成几条硬性规范所有涉及跨数据库方言的变更集必须写dbms判断并且显式指定onFailCONTINUE。所有建表、加列、加索引、删对象的变更集尽量用对象存在性判断包裹避免手工改动过的库重复执行报错。所有自定义sqlCheck必须保证返回一行一列值统一用数字1或0不许出现布尔写法。代码评审时preConditions和它保护的变更集必须一起审禁止只审SQL不审判断逻辑。危险变更删表、删列、大批量UPDATE的建议策略是HALT宁可停住人工介入也不要让它带着错误前提继续往下跑。Liquibase的preConditions不是一套复杂机制但它把“数据库当前状态是否允许执行变更”这件事从运维经验和外部脚本里解放出来变成了变更描述文件的一部分。我在实际项目里最大的体会是它真正的价值不只是防报错而是让每个变更集都能对“数据库已经在任意中间状态”这件事保持容忍。线上环境永远会有DBA手工处理过的残留、历史脚本留下的半成品、不同环境之间的差异preConditions就是那个帮你把数据库状态“收敛”到终态的保险丝。最后分享一个我一直在用的小技巧在本地开发环境拿到一份陌生changelog时先用updateSQL把所有preConditions提前跑一遍观察哪些变更集在当前库会被跳过、哪些会被HALT。这一步能帮你快速理解整份changelog的边界条件上线前做一次同样的预检也能避免把“条件不满足误伤”带进生产环境。