changeSet tag

The changeSet tag is what you use to group database changes/refactorings together.

<?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>

Each changeSet tag is uniquely identified by the combination of the “id” tag, the “author” tag, and the changelog file classpath name. The id tag is only used as an identifier, it does not direct the order that changes are run and does not even have to be an integer. If you do not know or do not wish to save the actual author, simply use a placeholder value such as “UNKNOWN”.

As Liquibase executes the databaseChangeLog, it reads the changeSets in order and, for each one, checks the “databasechangelog” table to see if the combination of id/author/filepath has been run. If it has been run, the changeSet will be skipped unless there is a true “runAlways” tag. After all the changes in the changeSet are run, Liquibase will insert a new row with the id/author/filepath along with an MD5Sum of the changeSet (see below) in the “databasechangelog”.

Note

filepath is the path how the changeLogFile parameter is defined. Even if the same file is referenced with a different path, that is considered a different file unless the logicalFilePath is defined.

Liquibase attempts to execute each changeSet in a transaction that is committed at the end, or rolled back if there is an error. Some databases will auto-commit statements which interferes with this transaction setup and could lead to an unexpected database state. Therefore, it is usually best to have just one change per changeSet unless there is a group of non-auto-committing changes that you want applied as a transaction such as inserting data.

Available Attributes

Available Sub-Tags

Rollback Tag

The rollback tag describes how to roll back a change using SQL statement(s), change tags, or a reference to a previous change set.

Rollback Tag Examples

Here we see that you can just have plain SQL in the content part of the <rollback> element. The text in the element is treated as a <sql> change with stripComments set to true, splitStatements set to true and endDelimiter set to ;.

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

Here we see that you can have any type of change in the <rollback> element.

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

This example shows how a <rollback> element can refer to another changeset. This would be interpreted as “In order to roll back this changeset (id=”2”), apply the changeset with id=1”

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

ChangeSet Check Sums

When Liquibase reaches a changeSet, it computes a check sum and stores it in the “databasechangelog”. The value of storing the check sum is so that Liquibase can know if someone changed the changes in the changeSet since it was run. If the changeSet was changed since it was run, Liquibase will exit the migration with an error message like Validation failed: change set check sums <changeset identifer> was: <old checksum> but is now: <newchecksum>. This is because Liquibase cannot know what was changed and the database may be in a state different than what the changeLog is expecting. If there was a valid reason for the changeSet to have been changed and you want to ignore this error, you have two options.

The first option is to manually update the databasechangelog table so that the row with the corresponding id/author/filepath has a null value for the check sum. You would need to do this for all environments where the changeset has been deployed. The next time you run the Liquibase update command, it will update the check sum value to the new correct value.

The second option is to add a <validCheckSum> element to the changeset. The text contents of the element should be the “old” checksum from the error message.

Check sums are also used in conjunction with the “runOnChange” changeSet attribute. There are times you may not want to add a new changeSet because you only need to know about the current version, but you want this change applied whenever it is updated. A good example of when you would want this is stored procedures. If you copy the entire text of the stored procedure to a new changeSet each time you make a change you will not only end up with a very long changeLog, but you will lose the merging and diff-ing power of your source control. Instead, put the text of the stored procedure in a changeSet with a runOnChange=”true” attribute. The stored procedure will be re-created when and only when there is a change to the text of it.