PostgreSQL的DDL通常支持事务回滚，但Liquibase执行迁移时并不是简单地把所有语句包进同一个事务。它会在目标数据库中维护一张 DATABASECHANGELOG 表，记录每个 changeSet 的 id、author、文件名、校验和与执行时间，同时用另一张 DATABASECHANGELOGLOCK 表防止多个实例并发迁移。理解这两张表的工作方式，是避免迁移事故的第一步。
在实际项目中，最常见的做法是把数据库变更脚本和业务代码放在同一个代码仓库，通过 CI/CD 在发布阶段调用 liquibase update。这样每次上线前，数据库结构会先被 Liquibase 计算差异并应用未执行的变更集。接下来分别从执行机制、变更集编写、回滚与多环境、以及校验和避坑几个角度展开。
一、先理清执行机制与PostgreSQL事务特性
Liquibase 在启动时会读取主变更日志，通常是 db.changelog-master.xml 或 YAML 文件，再按顺序解析其中的 <changeSet>。每个 changeSet 有唯一标识，Liquibase 会先到 DATABASECHANGELOG 表里查询该标识是否已经存在。如果不存在，就执行变更体；执行完成后在同一事务中写入日志记录。这里的关键点是：如果变更体内部包含多个 SQL 语句，而数据库驱动和数据库本身支持事务性 DDL，那么在 PostgreSQL 中大多数情况下可以做到原子迁移。
但 PostgreSQL 里有几类语句不能在事务块中执行，最典型的是 CREATE INDEX CONCURRENTLY、ALTER TYPE ... ADD VALUE 在老版本中的使用，以及某些扩展管理命令。对于这些语句，如果仍然放在默认的 <changeSet> 中，Liquibase 会因为 PostgreSQL 抛出错误而中断。解决办法是给 changeSet 设置 runInTransaction="false"，让该变更集在自动提交模式下执行。不过一旦脱离事务，失败后就无法自动回滚已执行的部分，所以这类变更要在 SQL 中预留判断逻辑，或者拆成多个小步骤。
下面是一个最小可用的 XML 主日志示例，它引入了一个外部变更文件，并定义初始账号表。该文件同时补充了 <rollback> 内容，以便后续执行 liquibase rollback 时删除表。
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.20.xsd">
<include file="changelog/001-init.xml" relativeToChangelogFile="true"/>
</databaseChangeLog>
二、用XML与原生SQL混合处理PostgreSQL对象
Liquibase 提供了一组内置重构标签，例如 <createTable>、<addColumn>、<createIndex>。它们的优点是写法清晰、能自动生成部分回滚逻辑，尤其在只涉及标准表结构和索引时，迁移文件可读性更高。但 PostgreSQL 的函数、触发器、序列、JSON 字段、部分索引等特性，很难用内置标签完整表达，此时直接使用 <sql> 标签嵌入原生 SQL 会更高效。
例如创建触发器函数，通常需要先使用 CREATE FUNCTION 声明函数体，再通过 CREATE TRIGGER 绑定到表。函数体内部包含分号，会干扰 Liquibase 默认的分号分割行为。可以通过 splitStatements="false" 关闭自动拆分，把整段函数交给 PostgreSQL 驱动执行，或者使用 endDelimiter 指定新的语句结束符。下面这段 SQL 变更集演示了创建更新时间触发器的方式，函数体中的分号因为关闭了拆分而未被打断。
-- liquibase formatted sql
-- changeset dev:20250601-trigger splitStatements:false
CREATE OR REPLACE FUNCTION set_updated_at()
RETURNS trigger AS $$
BEGIN
NEW.updated_at := now();
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER account_set_updated_at
BEFORE UPDATE ON account
FOR EACH ROW
EXECUTE FUNCTION set_updated_at();
-- rollback DROP TRIGGER account_set_updated_at ON account;
如果需要使用 formatSql 这样的变更集属性，也可以写在注释行中。Liquibase 支持 SQL 格式的变更日志，它会把以 -- liquibase formatted sql 开头的文件当作变更集解析，-- changeset 行后可以附加多个属性。对于团队中更熟悉 SQL 而不是 XML 的成员，这种方式上手更快。但 SQL 格式的变更文件在跨数据库方言时不如 XML 通用，如果项目锁定 PostgreSQL，这个劣势可以被忽略。
内置重构也不是没有用处。比如创建表时如果需要精确控制主键、自增序列和默认值，<createTable> 配合 <column> 可以减少手写拼写错误。但 PostgreSQL 的 BIGSERIAL 在 Liquibase 中常通过 autoIncrement="true" 和 type="bigint" 来表达，最终生成序列与默认值。如果团队有严格的 SQL 审核流程，直接写原生 CREATE TABLE 反而更容易审查。
三、回滚策略与多环境差异化发布
回滚是数据库版本管理中最容易被低估的部分。Liquibase 并不会自动推导所有回滚脚本，只有一部分内置重构标签可以根据变更内容自动生成反向操作。对于自定义 SQL，必须在 <rollback> 标签中显式写出反向语句。如果不写，执行 liquibase rollback 时会提示无法回滚。对于无法安全回滚的变更，例如删除列后数据已丢失，可以写 <rollback changeSetId="..." changeSetAuthor="..."/> 引用另一个补偿变更，或者使用 <empty/> 声明该变更不可回滚。
在多环境场景中，开发、测试和生产的数据库并非完全一致。生产可能需要额外的只读副本索引、更细粒度的权限，测试环境需要播种数据。Liquibase 的 contexts 与 labels 机制可以解决这个问题。例如给一个创建索引的 changeSet 标记 context="prod"，执行开发环境迁移时加上 --contexts=dev 就不会应用该变更。labels 则可以从运行环境角度筛选变更集，比如标记 labels="noprod" 表示只允许非生产环境执行。
<changeSet id="20250601-add-prod-index" author="ops" context="prod">
<createIndex indexName="idx_order_created_at" tableName="orders">
<column name="created_at"/>
</createIndex>
<rollback>
DROP INDEX idx_order_created_at;
</rollback>
</changeSet>
日常发布时最好再结合 tag 命令。例如在发布前执行 liquibase tag release-20250601，给当前数据库状态打一个标签。如果发布后发现问题，需要回滚到上一个稳定状态，可以执行 liquibase rollback release-20250601。不过要注意，rollback 依赖每个 changeSet 的回滚定义，标签本身并不能代替有效的回滚脚本。生产环境回滚更应该先在测试库模拟，避免再次引入新的数据问题。
四、校验和冲突与协作中常见错误
Liquibase 为每个 changeSet 计算校验和，并将它保存在 DATABASECHANGELOG 表中。任何人修改了已经应用过的 changeSet，Liquibase 再次运行时就会发现校验和与记录不一致，直接报错停止。这是为了防止历史迁移被悄悄修改而导致环境漂移。很多团队第一次遇到这个错误，会选择清空 DATABASECHANGELOG 表或手动删除校验和，结果让数据库状态和版本记录完全脱节。
正确的做法是遵循“已应用的变更集不可修改”原则。结构需要调整时，新增一个 changeSet 完成 ALTER TABLE 或数据修复。如果某个视图或函数需要反复更新，可以设置 runOnChange="true"，这样 Liquibase 在内容变化时会重新执行该变更集，并以新的校验和覆盖旧记录。但 runOnChange 只适合可重复执行的对象，例如 CREATE OR REPLACE VIEW、CREATE OR REPLACE FUNCTION。对于表结构变更，重复执行可能导致重复加列或索引冲突。
<changeSet id="20250601-refresh-active-view" author="dev" runOnChange="true">
<createView viewName="active_account_view">
SELECT id, email FROM account WHERE status = 'active'
</createView>
</changeSet>
PostgreSQL 的锁行为也会影响迁移。默认的 ALTER TABLE ... ADD COLUMN 在大多数新版本里可以快速完成，但如果同时修改大量行并设置默认值，可能触发较长时间的锁等待。执行 Liquibase 迁移前，应确认目标表没有长时间未提交的事务，必要时设置 lockWaitTimeInSeconds 或使用 CREATE INDEX CONCURRENTLY 并在外部单步验证。数据库账号需要具有创建表、修改表、创建触发器、管理锁的权限，尽量使用独立迁移账号而不是超级用户，降低误操作影响范围。把这些边界提前定好，Liquibase 才能从工具层真正提升 PostgreSQL 的发布可靠性。
PostgreSQLLiquibase数据库版本管理修改时间：2026-10-04 10:18:30