Uses

You can use preconditions to:

• Document what assumptions the author 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 dropTable.

• Control what changesets are run and not run based on the state of the database.

You can use all Liquibase preconditions in XML, YAML, and JSON changelogs. Only some preconditions are supported in SQL changelogs.

Syntax

You can use one local preConditions tag per changeset and one global preConditions tag in the changelog (outside any changeset). In XML, YAML, and JSON changelogs, you can use conditional logic to add multiple preconditions within a single preConditions tag.

Preconditions at the changelog level are applied to all changesets, not just those listed in the current changelog or its child changelogs.

The following example XML, YAML, and JSON changelogs will only be run if the database executed against is Oracle and the database user executing the script is SYSTEM. Also, they will run the changeset with the sqlCheck precondition and createTable. The example SQL changelog only runs the sqlCheck precondition and createTable.

If the preconditions check fails, you will receive a warning and it will continue executing the changeset as normal because of the onFail="WARN" precondition. To prevent the execution of the changeset when the precondition fails, you can set HALT or CONTINUE values. For more information, see onFail/onError precondition values.

Example changelogs with preconditions

Note: The syntax on this page explains how to specify preconditions directly in changelogs. In Liquibase 4.29.2 and later, if you're calling on the Liquibase API programmatically using the YamlChangeLogSerilizer or JsonChangeLogSerializer classes, YAML and JSON preconditions have slightly different syntax. For more information, see liquibase.serializer.ChangeLogSerializer.

Multiple preconditions

In XML, JSON, and YAML changelogs, you can set multiple preconditions in one preConditions tag by using nestable AND, OR, and NOT conditional logic tags. If no conditional tags are specified, the default value is AND.

Liquibase uses lazy evaluation (call-by-need) when running preconditions. For example, if the first condition of an AND expression fails, Liquibase does not evaluate the second condition. If the first condition of an OR expression succeeds, Liquibase does not evaluate the second condition.

Handling failures and errors

Liquibase defines two types of preconditions:

• Precondition failures, which represent that the check failed

• Precondition errors that are the exceptions thrown in the execution of a check

The process of both can be controlled through the onFail and onError attributes on the preConditions tag.

Available attributes

onFail/onError precondition values

onSqlOutput/onUpdateSql values

Failures and errors will cause Liquibase to return non-zero exit codes in the command output. Warnings will cause Liquibase to return exit codes of zero.

Available preconditions

The examples of preconditions shown in the table don't include the schemaName attribute. It is best practice not to keep the schemaName in the changeset and rely on the default schema except when you don't want to create something in the default schema.

Additionally, you can include the onError or onFail attributes with the WARN, HALT, CONTINUE, or MARK_RAN value in the preconditions tag, however, the CONTINUE and MARK_RAN options can only be applied to preconditions inside a changeset.

changeLogPropertyDefined

Checks whether given changelogattribute is present. It fails if the value is not the same as given.

changeSetExecuted

Defines if the specified changeset has already been executed.

columnExists

Defines if the specified column exists in the database.

Note: Liquibase initially tries to run this precondition with a resource-efficient database query. If it fails, it creates a snapshot of your database, which may impact performance.

dbms

Defines if the database executed against matches the type specified.

Note: The dbms precondition is not available for formatted SQL.

expectedQuotingStrategy

Controls how object names are quoted in the SQL files generated by Liquibase and used in calls to the database. For more information, see objectQuotingStrategy.

foreignKeyConstraintExists

Defines if the specified foreign key exists in a table in the database.

Note: Running this precondition always creates a snapshot of your database, which may impact performance.

indexExists

Defines if the specified index exists in the database. You can either specify the indexName attribute or tableName and columnNames attributes.

Note: There are a few databases where the indexName is not unique, which is why both indexName and tableName can be used.

Note: Running this precondition always creates a snapshot of your database, which may impact performance.

primaryKeyExists

Defines if the specified primary key exists in the database.

Note: Running this precondition always creates a snapshot of your database, which may impact performance.

rowCount

Checks that the number of rows in a table matches an expected value.

runningAs

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

Note: The runningAs precondition is not available for formatted SQL.

sequenceExists

Defines if the specified sequence exists in the database.

Note: If you use PostgreSQL, Liquibase initially tries to run this precondition with a resource-efficient database query. If it fails, it creates a snapshot of your database, which may impact performance. On other databases, Liquibase always creates a snapshot.

sqlCheck

Executes an SQL string and checks the returned value. The SQL must return a single row with a single value.

• To check a number 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.

tableExists

Defines if the specified table exists in the database.

Note: Running this precondition always creates a snapshot of your database, which may impact performance.

tableIsEmpty

Checks whether the specified table is empty.

uniqueConstraintExists

Checks for the existence of unique constraints before running the update. (since Liquibase 4.9.0)

Note: Running this precondition always creates a snapshot of your database, which may impact performance.

viewExists

Defines if the specified view exists in the database.

Note: Running this precondition always creates a snapshot of your database, which may impact performance.

customPrecondition

Can be created by adding a class that implements the liquibase.precondition.CustomPrecondition interface. Parameters on custom classes are set through reflection based on the <param> sub-tags. Pass parameters as strings to the custom precondition.

<param> sub-tag

The parameter to pass to the custom precondition.