[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"?>
<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引入其他版本修改历史文件，如下图：
![[Liquibase]配置文件详解_第1张图片](http://img.e-com-net.com/image/info8/4c3b21d7d4984e5cb27545a736b81d35.jpg)
严格来说，其实存在四种格式，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标签
可以应用于
示例：
<?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
示例：
<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 type="mysql" />
<runningAs username="root" />
<changeSetExecuted id="1" author="YoungLu" changeLogFile="classpath:liquibase/changelog/2020-02-11-change.xml" />
<columnExists schemaName="young_webchat" tableName="y_user" columnName="username" />
<tableExists schemaName="young_webchat" tableName="y_user" />
<viewExists schemaName="young_webchat" viewName="y_user_view" />
<foreignKeyConstraintExists schemaName="young_webchat" foreignKeyName="y_user_log_fk" />
<indexExists schemaName="young_webchat" indexName="y_user_idx" />
<sequenceExists schemaName="young_webchat" sequenceName="y_user_seq" />
<primaryKeyExists schemaName="young_webchat" primaryKeyName="y_user_id" />
<sqlCheck expectedResult="1">SELECT COUNT(1) FROM pg_tables WHERE TABLENAME = 'myRequiredTable'sqlCheck>
<changeLogPropertyDefined property="myproperty"/>
<changeLogPropertyDefined property="myproperty" value="requiredvalue"/>
<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 | 前置条件，例如做一些不可逆操作前的必要检查 |
| 要作为这个更改集的一部分运行的数据库更改 | |
| 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拆分为易于管理的部分。
例如：
<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 ...