[Liquibase]配置文件详解

文章目录

  • 数据库更改日志文件
    • 一、XML格式
      • 1.preConditions标签
        • (1)处理失败和错误
          • OnFail/OnError值可能配置的值
          • onSqlOutput可能配置的值
        • (2)and/or/not逻辑
        • (3)可用的preConditions
      • 2.Properties标签
        • 可用的配置项
      • 3. changeSet标签
        • (1)可用的属性值：
        • (2)可用的子标签
      • 4.include标签
    • 二、sql格式（2.0以后支持）
      • 1.Changesets
        • 可用的属性值
      • 2.Preconditions
      • 3.Rollback
      • 4.Comment
      • 5.Valid CheckSum
      • 6.Ignore lines

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

数据库更改日志文件

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

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLogxmlns="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.xsdhttp://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsdhttp://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"?><databaseChangeLogxmlns="http://www.liquibase.org/xml/ns/dbchangelog"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangeloghttp://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定义一个参数。给定上下文 和/或 数据库的列表，该参数将仅在这些上下文 和/或 数据库中使用。

示例：

<databaseChangeLogxmlns="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.xsdhttp://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"?><databaseChangeLogxmlns="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.xsdhttp://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"?><databaseChangeLogxmlns="http://www.liquibase.org/xml/ns/dbchangelog"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangeloghttp://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 ...

Published by

风君子

独自遨游何稽首 揭天掀地慰生平