Liquibase splitStatements参数作用、配置优势及运行机制咨询

基础规则说明 #

• 验证基准版本：org.liquibase:liquibase-core:3.8.2（非商业Pro版）
• 参数默认行为：splitStatements 默认值为 true，未手动配置时，Liquibase会自动按;、GO关键字拆分SQL脚本；设置为false时，Liquibase侧完全关闭语句拆分逻辑。

1. 开启splitStatements=true的实际价值 #

很多人觉得数据库本身就能识别分号，Liquibase做拆分属于多此一举，实际上两者执行逻辑有本质区别：开启拆分时，Liquibase会把拆好的单条SQL逐次调用JDBC接口执行；关闭拆分时，整段SQL会作为一个完整字符串一次性提交给驱动。两者的实际差异体现在3个方面：

• 兼容低版本/小众数据库驱动：不少老版本JDBC驱动（比如Oracle ojdbc14、早期SQL Server驱动）根本不支持单次提交多条带分号的SQL，整段提交会直接报无效字符、语法错误，拆分后单条执行可以兼容这类场景。
• 错误定位更高效：逐句执行时，Liquibase的错误日志会直接打印失败的具体SQL语句、在脚本中的位置；如果整段提交，驱动只会返回整段文本的字符偏移量，排查错误需要手动定位到具体行，效率极低。
• 严格匹配failOnError配置预期：部分数据库（比如MySQL）的DDL语句是隐式提交的，整段提交多语句时，驱动可能在某条语句失败后继续执行后续语句，导致变更结果不符合预期；拆分后逐句执行时，Liquibase会在单条语句报错后立刻终止整个变更集，严格遵循failOnError的配置逻辑。

2. 配置splitStatements=false的优势及适用场景 #

关闭拆分不是无意义的配置，在特定场景下能解决默认拆分处理不了的问题：

• 兼容带内嵌分号的复杂SQL：这是最常用的场景。编写存储过程、自定义函数、触发器这类逻辑块时，语句内部本身就存在大量分号作为语法结束符，默认的拆分逻辑会把完整的逻辑块拆成残缺的片段，直接执行报错。比如PostgreSQL的触发器函数：

-- 这类语句必须配置splitStatements:false才能正常执行
CREATE OR REPLACE FUNCTION update_modified_time()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW(); -- 此处的分号如果被Liquibase误判为语句结束符，整个函数会被拆碎
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

• 提升批量SQL执行效率：如果是批量初始化数据、批量加索引这类包含大量短SQL的变更集，整段提交给数据库后，驱动和数据库可以一次性完成语法解析、执行计划生成，相比逐句提交执行效率提升明显，数据量越大差异越显著。
• 规避默认拆分的已知bug：3.8.x版本的拆分逻辑存在已知兼容问题，会误判字符串内部的分号（比如字段值里包含;）、空行、特殊注释位置的分隔符，导致正常SQL被拆错执行失败，关闭拆分可以彻底规避这类问题。

3. 为什么splitStatements=false时，PostgreSQL脚本带分号仍能正常执行 #

这里首先要纠正一个普遍认知偏差：splitStatements=false从来不是要求SQL里不能出现分号，只是Liquibase自己不做拆分，会把原始SQL原封不动传给JDBC驱动和数据库处理。
你贴的生产环境脚本可以正常执行，底层逻辑非常简单：PostgreSQL官方JDBC驱动从很早的版本开始，就原生支持多语句执行能力——驱动收到整段带分号的SQL后，会自己在驱动侧完成语句拆分，再逐次发送给数据库执行，完全不需要Liquibase提前做拆分。
很多人误以为“关闭拆分就不能写带分号的多语句”，本质是踩了不同驱动的能力差异：不是所有数据库的JDBC驱动都支持多语句解析，比如Oracle 11g及更早版本的ojdbc驱动、老版本SQL Server驱动默认就不支持这个能力，这类场景下关闭拆分后传多语句才会报语法错误，和Liquibase本身的配置逻辑无关。

你提到的生产环境变更集可正常执行的参考代码如下：

--liquibase formatted sql

--changeset adam:001-users-001 failOnError:true splitStatements:false logicalFilePath:001-users.sql

CREATE TABLE sys_users
(
  user_id SERIAL,
  first_name character varying(64) NOT NULL,
  last_name character varying(64) NOT NULL,
  email character varying(255) NOT NULL
)
WITH (
  OIDS=FALSE
);

CREATE TABLE user_role
(
  role_id SERIAL,
  role_name character varying(255) NOT NULL,
  description character varying(255) NOT NULL,
  created_on timestamp(6) with time zone NOT NULL,
  created_by character varying(64) NOT NULL
)
WITH (
  OIDS=FALSE
);

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