LiquiBase: <preConditions>

Preconditions can be attached to change logs or changesets to control the execution of an update based on the state of the database.

There are several reasons to use preconditions, including:

• Document what assumptions the writers of the changelog had when creating it.
• Enforce that those assumptions are not violated by users running the changelog
• Perform data checks before performing an unrecoverable change such as drop_Table
• Control what changesets are run and not run based on the state of the database

If desired, a precondition can be the only tag in a <changeSet>.

<?xml version="1.0" encoding="UTF-8"?>
 
<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog/1.8"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog/1.8
         http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-1.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>

The above changelog will only run if the database executed against is Oracle and the database user executing the script is “SYSTEM”. It will also only run the drop_Table command if there are no values in the “oldtable”.

LiquiBase distinguishes between precondition “failures” (check failed) and “errors” (exception thrown in execution of check) and the reaction to both can be controlled via the “onFail” and “onError” attributes on the <preConditions> tag. Since 1.8

Conditional logic can be applied to preconditions using nestable <and>, <or> and <not> tags. If no conditional tags are specified, it defaults to AND.

Examples:

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

Will check that the update is running on Oracle AND with the SYSTEM user, but will only generate a warning if the precondition fails.

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

Will require running on Oracle AND MySQL, which will always be false, unless a huge and unexpected merger takes place.

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

Will require running on Oracle OR MySQL which makes more sense than the above example.

 <preConditions>
     <or>
         <and>
            <dbms type="oracle" />
            <runningAs username="SYSTEM" />
         </and>
         <and>
            <dbms type="mssql" />
            <runningAs username="sa" />
         </and>
     </or>
 </preConditions>

Will require running as SYSTEM if executing against an Oracle database or running as SA if running against a MS-SQL database.

Passes if the database executed against matches the type specified.

Passes if the database user executed under matches the username specified.

Passes if the specified change set has already been executed. Since 1.8

Passes if the specified column exists in the database. Since 1.8

Passes if the specified table exists in the database. Since 1.8

Passes if the specified view exists in the database. Since 1.8

Passes if the specified foreign key exists in the database. Since 1.8

Passes if the specified index exists in the database. Since 1.8

Passes if the specified sequence exists in the database. Since 1.8

Passes if the specified primary key exists in the database. Since 1.8

Executes an SQL string and checks the returned value. The SQL must return a single row with a single value. To check numbers of rows, use the “count” SQL function. To check for ranges of values, perform the check in the SQL and return a value that can be easily compared against.

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

Custom preconditions can be created by creating a class that implements the liquibase.precondition.CustomPrecondition interface. Parameters on custom classes are set through reflection based on the <param> sub-tags. Parameters are passed as strings to the custom precondition.

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

Preconditions are checked at the beginning of the execution of a particular changelog. If you use the “include” tag and only have preconditions on the child changelog, those preconditions will not be checked until the migrator reaches that file. This behavior may change in future releases, so don't rely on this behavior.