[Liquibase]配置文件详解

大致搜了下liquibase的使用，所有人都是写的怎么简单使用，给个示例就完结了，10个人的文章，9个人抄1个人的，没有人写怎么使用的详细文档。只能找下官方文档，做了一些验证和整理，方便想要学习了解liquibase的英文不好的学习者。

数据库更改日志文件

即databaseChangeLog文件，Liquibase入口文件。这个文件里可以引入你的版本修改文件，执行顺序为从上到下。
示例（XML）：

<?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"
    xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd
    http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
    http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-3.8.xsd ">
</databaseChangeLog>

可以用include引入其他版本修改历史文件，如下图：

严格来说，其实存在四种格式，XML、YAML、JSON、SQL：

同XML格式相同含义的YAML格式文件可以表示为：

databaseChangeLog:

JSON格式：

{
    "databaseChangeLog": [
    ]
}

SQL格式：

--liquibase formatted sql

一、XML格式

tag	Description
preConditions	执行sql变更文件的前置条件
property	设置的属性的值
changeSet	要执行的更改
include	包含要执行的更改集的附加文件
context	上下文将被附加到(使用AND)所有变更集

1.preConditions标签

可以应用于<databaseChangeLog>标签或者<changeSet>标签。
示例：

<?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-3.8.xsd">
    <preConditions>
        <dbms type="oracle" />
        <runningAs username="SYSTEM" />
    </preConditions>

    <changeSet id="1" author="bob">
        <preConditions onFail="WARN">
            <sqlCheck expectedResult="0">select count(*) from oldtable</sqlCheck>
        </preConditions>
        <comment>Comments should go after preCondition. If they are before then liquibase usually gives error.</comment>
        <dropTable tableName="oldtable"/>
    </changeSet>
</databaseChangeLog>

上述的示例，是只有在Oracle数据库以及用户是SYSTEM时才会执行。

preConditions前置条件分为正常和异常情况：
正常情况下，无论返回的值是不是预料的值（0），oldtable都会被删除，只是如果不是预料的值，这里会给出WARN；
异常情况下，也就是如果oldtable不存在，删除oldtable的命令将不会执行。

(1)处理失败和错误

Attribute	Description
onFail	当preConditions是失败情形下如何处理
OnError	当preConditions是错误情形下如何处理
onSqlOutput	在updateSQL模式下要做什么
onFailMessage	输出的失败信息
onErrorMessage	输出的错误信息

OnFail/OnError值可能配置的值

Value	Description
HALT	立即停止执行整个更改日志。 [默认]
CONTINUE	跳过* changeSet 。 下次更新时将再次尝试执行更改集。 继续 changelog *。
MARK_RAN	跳过更改集，但将其标记为已执行。继续更改日志。
WARN	输出警告并继续照常执行* changeSet * / * changelog *。

onSqlOutput可能配置的值

Value	Description
TEST	在updateSQL模式下运行changeSet
FAIL	使preConditons在updateSQL模式下失败
IGNORE	忽略updateSQL模式中的preConditons(默认)。

(2)and/or/not逻辑

可以使用nestable <and>、<or>和<not>标记将条件逻辑应用于前置条件。如果没有指定条件标记，则默认为AND。

示例：

<preConditions onFail="WARN">
    <dbms type="oracle" />
    <runningAs username="SYSTEM" />
</preConditions>

这里就是默认值AND，也就是同时满足既是oracle数据库，并且用户必须是SYSTEM才会执行。

如果使数据更改可以在oracle和mysql中可以执行，需要用到or表达式：

 <preConditions>
     <or>
         <dbms type="oracle" />
         <dbms type="mysql" />
     </or>
 </preConditions>

复合条件，例如，是oracle数据库，并且用户必须是SYSTEM 或者 数据库是mysql，且用户需要为root时，可以这样写：

 <preConditions>
     <or>
         <and>
            <dbms type="oracle" />
            <runningAs username="SYSTEM" />
         </and>
         <and>
            <dbms type="mysql" />
            <runningAs username="root" />
         </and>
     </or>
 </preConditions>

(3)可用的preConditions

• <dbms>:如果针对指定类型执行的数据库匹配，则可以传递。

<dbms type="mysql" />

• <runningAs>:执行执行的用户，匹配才可以传递。

<runningAs username="root" />

• <changeSetExecuted>:如果指定的changeSet被执行了才可以传递。

<changeSetExecuted id="1" author="YoungLu" changeLogFile="classpath:liquibase/changelog/2020-02-11-change.xml" />

• <columnExists>:如果数据库中的指定列存在则传递

<columnExists schemaName="young_webchat" tableName="y_user" columnName="username" />

• <tableExists>:如果数据库中的表存在，则传递

<tableExists schemaName="young_webchat" tableName="y_user" />

• <viewExists>:如果数据库中的视图存在，则传递

<viewExists schemaName="young_webchat" viewName="y_user_view" />

• <foreignKeyConstraintExists>:如果外键存在则传递

<foreignKeyConstraintExists schemaName="young_webchat" foreignKeyName="y_user_log_fk" />

• <indexExists>:如果索引存在则传递

<indexExists schemaName="young_webchat" indexName="y_user_idx" />

• <sequenceExists>：如果序列存在则传递

<sequenceExists schemaName="young_webchat" sequenceName="y_user_seq" />

• <primaryKeyExists>:如果主键存在则传递

<primaryKeyExists schemaName="young_webchat" primaryKeyName="y_user_id" />

• <sqlCheck>:执行SQL检查。SQL必须返回具有单个值的单个行。

<sqlCheck expectedResult="1">SELECT COUNT(1) FROM pg_tables WHERE TABLENAME = 'myRequiredTable'</sqlCheck>

• <changeLogPropertyDefined>:检查给定的changelog参数是否存在。如果一个值也是给定的，如果这个值与给定的值不相同那么它只会失败。

<changeLogPropertyDefined property="myproperty"/>
<changeLogPropertyDefined property="myproperty" value="requiredvalue"/>

• <customPrecondition>:可以通过创建实现liquibase.precondition的类来创建自定义前置条件。CustomPrecondition接口。自定义类的参数是通过基于子标记的反射设置的。参数作为字符串传递给自定义前置条件。

<customPrecondition className="com.example.CustomTableCheck">
    <param name="tableName" value="our_table"/>
    <param name="count" value="42"/>
</customPrecondition>

2.Properties标签

为changelog定义一个参数。给定上下文 和/或 数据库的列表，该参数将仅在这些上下文 和/或 数据库中使用。

示例：

<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd">

    <property name="clob.type" value="clob" dbms="oracle"/>
    <property name="clob.type" value="longtext" dbms="mysql"/>

    <changeSet id="1" author="joe">
         <createTable tableName="${table.name}">
             <column name="id" type="int"/>
             <column name="${column1.name}" type="${clob.type}"/>
             <column name="${column2.name}" type="int"/>
         </createTable>
    </changeSet>
</databaseChangeLog>

可用的配置项

Attribute	Description
name	表的数据库名称
value	所需列的表的名称
context	上下文，逗号分隔
dbms	要用于该changeSet 的数据库的类型。关键字all和none也可用。
global	定义属性是全局的还是局限于databaseChangeLog。“true”或“false”。

示例：

<property name="simpleproperty" value="somevalue"/>
<property name="clob.type" value="clob" dbms="oracle,h2"/>
<property name="clob.type" value="longtext" dbms="mysql"/>
<property name="myproperty" value="yes" context="common,test"/>
<property name="localproperty" value="foo" global="false"/>

3. changeSet标签

将一个个数据库更改分开。

示例：

<?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"
  xmlns:pro="http://www.liquibase.org/xml/ns/pro"
  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd
      http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-3.8.xsd">
    <changeSet id="1" author="bob">
        <comment>A sample change log</comment>
        <createTable/>
    </changeSet>
    <changeSet id="2" author="bob" runAlways="true">
        <alterTable/>
    </changeSet>
    <changeSet id="3" author="alice" failOnError="false" dbms="oracle">
        <alterTable/>
    </changeSet>
    <changeSet id="4" author="alice" failOnError="false" dbms="!oracle">
        <alterTable/>
    </changeSet>

</databaseChangeLog>

一般主要由“id” 、“author”、changelog文件路径名组成

(1)可用的属性值：

属性	描述
id	唯一识别，不一定是数字
author	作者
dbms	数据库类型
runAlways	在每次运行时执行changeset ，即使之前已经运行过
runOnChange	在第一次看到更改时执行更改，并且在每次changeset 时执行更改
context	控制是否执行changeset，这取决于运行时设置。任何字符串都可以用于上下文名称，它们被不区分大小写地选中。
labels	控制是否执行changeset，这取决于运行时设置。任何字符串都可以用于标签名称，并且不区分大小写地选中它们。
runInTransaction	是否应该将changeset作为单个事务运行(如果可能的话)?默认值为true。
failOnError	如果在执行changeset时发生错误，迁移是否应该失败
objectQuotingStrategy	这控制了在生成的SQL中如何引用对象名，或者在对数据库的调用中如何使用对象名。不同的数据库对对象的名称执行不同的操作，例如Oracle将所有内容都转换为大写(除非使用引号)。有三个可能的值。默认值是LEGACY。三个配置的值： LEGACY - Same behavior as in Liquibase 2.0 QUOTE_ALL_OBJECTS - 每个对象都加上双引号 ：person becomes “person”.QUOTE_ONLY_RESERVED_WORDS - 在保留关键字和可用列名上面加双引号

(2)可用的子标签

value	description
comment	注释
preConditions	前置条件，例如做一些不可逆操作前的必要检查
<Any Refactoring Tag(s)>	要作为这个更改集的一部分运行的数据库更改
validCheckSum	添加一个校验和，不管数据库中存储了什么，它都被认为对这个changeset是有效的。主要用于需要更改changeset，并且不希望在已经运行了changeset的数据库上抛出错误(不推荐使用此过程)
rollback	描述如何回滚更改集的SQL语句或重构标记

着重讲一下rollback标签的示例：

<changeSet id="1" author="bob">
    <createTable tableName="testTable">
    <rollback>
        drop table testTable
    </rollback>
</changeSet>

<changeSet id="1" author="bob">
    <createTable tableName="testTable">
    <rollback>
        <dropTable tableName="testTable"/>
    </rollback>
</changeSet>

<changeSet id="2" author="bob">
    <dropTable tableName="testTable"/>
    <rollback changeSetId="1" changeSetAuthor="bob"/>
</changeSet>

这里发生了回滚，会调用id为1的changeSet 。

4.include标签

将change-logs拆分为易于管理的部分。

例如：

<?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-3.8.xsd">
    <include file="com/example/news/news.changelog.xml"/>
    <include file="com/example/directory/directory.changelog.xml"/>
</databaseChangeLog>

可用的配置项：

Attribute	Description
file	被引入的文件
relativeToChangelogFile	用文件的相对路径而不是classpath
context	向所有包含的changeSets追加上下文(使用AND)

二、sql格式（2.0以后支持）

每一个sql文件都以--liquibase formatted sql开头。
一个SQL格式的changeSet范例：

--liquibase formatted sql

--changeset nvoxland:1
create table test1 (
    id int primary key,
    name varchar(255)
);
--rollback drop table test1;

--changeset nvoxland:2
insert into test1 (id, name) values (1, ‘name 1′);
insert into test1 (id, name) values (2, ‘name 2′);

--changeset nvoxland:3 dbms:oracle
create sequence seq_test;

1.Changesets

格式化的SQL文件中的每个changeSets都以表单的注释开始:

--changeset author:id attribute1:value1 attribute2:value2 [...]

changeset 注释后面是一个或多个SQL语句，用分号(或属性的值)分隔。

可用的属性值

Attribute	Description
stripComments	执行sql前去除所有注释去执行，默认为true
splitStatements	设置为false，表示没有liquibase分割语句 ; 和 GO 。如果未设置，则默认为true
rollbackSplitStatements	同上，但用于回滚的SQL
endDelimiter	结束的分隔符，默认 ;
runAlways	每次运行都执行该SQL
rollbackEndDelimiter	回滚的结束分隔符
runOnChange	修改后每次都执行
context	如果在运行时传递了特定的上下文，则执行更改。任何字符串都可以用于上下文名称，它们被不区分大小写地选中。
logicalFilePath	用于在创建chageSet的唯一标识符时重写文件名和路径。在移动或重命名更改日志时需要。
labels	标签用于对changeSet分类
runInTransaction	默认为true。changeSet是否运行在一个事务里面
failOnError	如果在执行变更集时发生错误，迁移是否应该失败
dbms	用于该changeSet的数据库
logicalFilePath	设置databasechangelog表中的逻辑文件路径，而不是执行liquibase的sql的物理文件位置。

2.Preconditions

--preconditions onFail:HALT onError:HALT
--precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM my_table

运行changeSet的前置条件，可参考上面xml的说明。

3.Rollback

--rollback SQL STATEMENT

回滚。

4.Comment

--comment: Some comment

注释

5.Valid CheckSum

校验和，不管数据库中存储的是什么，它都被认为对这个changeSet有效。主要用于当您需要更改更改集，并且不希望在已经运行该更改集的数据库上抛出错误(不推荐使用此过程)时(这个不是很明白)

--validCheckSum: 3:098f6bcd4621d373cade4e832627b4f6
--validCheckSum: 7:ad0234829205b9033196ba818f7a872b

6.Ignore lines

允许忽略一些行。 与其他SQL工具一起使用同一脚本时很有用。

--changeset author:id1
CREATE OR REPLACE PACKAGE ...
--ignoreLines:2
/
show errors;
--changeset author:id2
CREATE OR REPLACE PACKAGE BODY ...

也可以用start和end标注：

--changeset author:id1
CREATE OR REPLACE PACKAGE ...
--ignoreLines:start
/
show errors;
--ignoreLines:end
--changeset author:id2
CREATE OR REPLACE PACKAGE BODY ...