What are preconditions?

Last updated: September 2, 2025

Preconditions are tags you add to your changelog or individual changesets to control the execution of an update based on the state of the database. Preconditions let you specify security and standardization requirements for your changesets. If a precondition on a changeset fails, Liquibase does not deploy that changeset.

Example failure on a changelog

Unexpected error running Liquibase: Validation Failed:
1 preconditions failed
myChangelog.xml : DBMS Precondition failed: expected oracle, got postgresql

Changelog syntax

--liquibase formatted sql --changeset Liquibase User:1 --preconditions onFail:WARN --precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM example_table --comment: /* Comments should go after the precondition. Otherwise, Liquibase returns an error. */ create table example_table ( id int primary key, firstname varchar(50), lastname varchar(50) not null, state char(2) )

Example error on a changelog

Unexpected error running Liquibase: Validation Failed:
1 preconditions generated an error
myChangelog.xml : liquibase.precondition.core.SqlPrecondition@5745ca0e : ERROR: relation "public.table_does_not_exist" does not exist

Changelog syntax for multiple preconditions

Syntax for multiple preconditions:

- preConditions: - or: - CONDITION_1: VALUE - CONDITION_2: SUB_CONDITION: SUB_VALUE

For example, the following syntax example checks that the update is running on Oracle and with the SYSTEM user but will only generate a warning message if the precondition fails:

- preConditions: - onFail: WARN - dbms: type: oracle - runningAs: username: SYSTEM

The following requires the changelog to run on Oracle or MySQL:

- preConditions: - or: - dbms: type: oracle - dbms: type: mysql

You can also see the precondition running as SYSTEM if executing against an Oracle database or running as SA if executing against a Microsoft SQL Server database:

- preConditions: - or: - and: - dbms: type: oracle runningAs: username: SYSTEM - and: - dbms: type: mssql runningAs: username: sa

Syntax for multiple preconditions:

- preConditions: - or: - CONDITION_1: VALUE - CONDITION_2: SUB_CONDITION: SUB_VALUE

For example, the following syntax example checks that the update is running on Oracle and with the SYSTEM user but will only generate a warning message if the precondition fails:

- preConditions: - onFail: WARN - dbms: type: oracle - runningAs: username: SYSTEM

The following requires the changelog to run on Oracle or MySQL:

- preConditions: - or: - dbms: type: oracle - dbms: type: mysql

You can also see the precondition running as SYSTEM if executing against an Oracle database or running as SA if executing against a Microsoft SQL Server database:

- preConditions: - or: - and: - dbms: type: oracle runningAs: username: SYSTEM - and: - dbms: type: mssql runningAs: username: sa

Example warning on a changelog

WARNING: Executing myChangelog.xml::01-new::wonder.woman despite precondition failure due to onFail='WARN':
1 preconditions failed
myChangelog.xml : Column public.customer.name_new does not exist

customPrecondition syntax

- customPrecondition: - className: com.example.CustomTableCheck - param: name: tableName value: our_table - param: name: count value: 42

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.

Attribute	Description	Requirement
`property`	The name of the property to check.	Required
`value`	The required value for a given property.	Optional

changeLogPropertyDefined syntax

- preConditions: - onFail: WARN - changeLogPropertyDefined: property: myproperty value: requiredvalue

changeSetExecuted

Defines if the specified changeset has already been executed.

Attribute	Description	Requirement
`id`	The changeset id.	Required
`author`	The changeset author.	Required
`changeLogFile`	The file name (including searchPath relative path) of the changeset.	Required

changeSetExecuted syntax

- preConditions: - onFail: HALT - changeSetExecuted: id: 1 author: liquibase changeLogFile: changelog.xml

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.

Attribute	Description	Requirement
`columnName`	The name of the column.	Required
`tableName`	The name of the column's table.	Required
`schemaName`	The name of the table's schema.	Optional

columnExists syntax

- preConditions: - onFail: WARN - columnExists: tableName: table1 columnName: column1

dbms

Defines if the database executed against matches the type specified.

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

Attribute	Description	Requirement
`type`	The type of database expected. Multiple dbms values can be specified using comma-separated values. For a list of valid values, see `dbms`.	Required

dbms syntax

- preConditions: - onFail: WARN - or: - dbms: type: oracle - dbms: type: mysql

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.

Attribute

Description

Requirement

strategy

The object quoting strategy. Valid values are

LEGACY

QUOTE_ALL_OBJECTS

, and

QUOTE_ONLY_RESERVED_WORDS

Required

expectedQuotingStrategy syntax

- preConditions: - onFail: WARN - expectedQuotingStrategy: strategy: LEGACY

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.

Attribute	Description	Requirement
`foreignKeyName`	The name of the foreign key.	Required
`foreignKeyTableName`	The name of the table the foreign key is in.	Required in 4.7.0+
`schemaName`	The name of the foreign key's schema.	Optional

foreignKeyConstraintExists syntax

- preConditions: - onFail: WARN - foreignKeyConstraintExists: foreignKeyName: PK_2354 foreignKeyTableName: myTable

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.

Attribute	Description	Requirement
`indexName`	The name of the index.	Optional
`columnNames`	The name of the column.	Optional
`tableName`	The name of the table.	Optional
`schemaName`	The name of the index's schema.	Optional

indexExists syntax

- preConditions: - onFail: WARN - indexExists: indexName: originindex

- preConditions: - onFail: WARN - indexExists: tableName: MY_NEW_TABLE columnNames: ID

- preConditions: - onFail: WARN - indexExists: indexName: originindex tableName: MY_NEW_TABLE

- preConditions: - onFail: WARN - indexExists: indexName: originindex

- preConditions: - onFail: WARN - indexExists: tableName: MY_NEW_TABLE columnNames: ID

- preConditions: - onFail: WARN - indexExists: indexName: originindex tableName: MY_NEW_TABLE

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.

Attribute	Description	Requirement
`primaryKeyName`	The name of the primary key constraint.	Either `tableName` or `primaryKeyName` is required
`tableName`	The name of the table containing primary key.	Either `tableName` or `primaryKeyName` is required Note: On DB2, H2, HSQLDB, MySQL, and SQLite, `tableName` is required even if you also specify `primaryKeyName`.
`schemaName`	The name of the primary key's schema.	Optional

primaryKeyExists syntax

- preConditions: - onFail: HALT - primaryKeyExists: primaryKeyName: ID_2354 tableName: table1

rowCount

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

Attribute	Description	Requirement
`expectedRows`	The number of rows the user expects in a table.	Required
`tableName`	The name of the column's table.	Required

rowCount syntax

- preConditions: - onFail: WARN - rowCount: expectedRows: 5 tableName: person

runningAs

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

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

Attribute	Description	Requirement
`username`	The database user script which is expected to run as.	Required

runningAs syntax

- preConditions: - onFail: WARN - dbms: type: oracle - runningAs: username: SYSTEM

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.

Attribute	Description	Requirement
`sequenceName`	The name of the sequence.	Required
`schemaName`	The name of the sequence's schema.	Optional

sequenceExists syntax

- preConditions: - onFail: WARN - sequenceExists: sequenceName: idnumber

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.

Attribute	Description	Requirement
`expectedResult`	The value to compare the SQL result to.	Required
`sql`	In JSON and YAML changelogs, the SQL statement to run. In XML changelogs, insert the SQL statement directly within the `<sqlCheck></sqlCheck>` tags. IN SQL changelogs, insert the SQL statement directly in the precondition header.	Required

sqlCheck syntax

--changeset your.name:1 --preconditions onFail:WARN --precondition-sql-check expectedResult:1 SELECT COUNT(1) FROM pg_tables WHERE TABLENAME = 'myRequiredTable' create table example_table ( id int primary key, firstname varchar(50), lastname varchar(50) not null, state char(2) )

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.

Attribute	Description	Requirement
`tableName`	The name of the table.	Required
`schemaName`	The name of the table's schema.	Optional

tableExists syntax

--changeset your.name:1 --preconditions onFail:MARK_RAN --precondition-table-exists table:table1 schema:12345 create table table2 ( id int primary key );

Note: tableExists is supported for SQL changelogs in Liquibase 4.27.0 and later.

--changeset your.name:1 --preconditions onFail:MARK_RAN --precondition-table-exists table:table1 schema:12345 create table table2 ( id int primary key );

Note: tableExists is supported for SQL changelogs in Liquibase 4.27.0 and later.

tableIsEmpty

Checks whether the specified table is empty.

Attribute	Description	Requirement
`tableName`	The name of the table.	Required
`catalogName`	The name of the database catalog.	Optional
`schemaName`	The name of the database schema.	Optional

tableIsEmpty syntax

- preConditions: - onFail: WARN - tableIsEmpty: tableName: myTable catalogName: myCatalog schemaName: mySchema

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.

Attribute	Description	Requirement
`tableName`	The name of the column's table.	Required
`columnNames`	The name of the column.	Optional
`constraintName`	The name of the unique constraint.	Optional

uniqueConstraintExists syntax

- preConditions: - onFail: WARN - uniqueConstraintExists: constraintName: uq_constraint_name tableName: test_table

- preConditions: - onFail: WARN - uniqueConstraintExists: tableName: test_table columnNames: first_name, last_name

- preConditions: - onFail: WARN - uniqueConstraintExists: constraintName: uq_constraint_name tableName: test_table

- preConditions: - onFail: WARN - uniqueConstraintExists: tableName: test_table columnNames: first_name, last_name

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.

Attribute	Description	Requirement
`viewName`	The name of the view.	Required
`schemaName`	The name of the view's schema.	Optional

viewExists syntax

Note: viewExists is supported for SQL changelogs in Liquibase 4.27.0 and later.

--changeset your.name:1 --preconditions onFail:MARK_RAN --precondition-view-exists view:view1 schema:12345 create table table1 ( id int primary key );

Note: viewExists is supported for SQL changelogs in Liquibase 4.27.0 and later.

--changeset your.name:1 --preconditions onFail:MARK_RAN --precondition-view-exists view:view1 schema:12345 create table table1 ( id int primary key );

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.

Attribute	Description	Requirement
`className`	The name of the custom precondition class.	Required

`<param>` sub-tag

The parameter to pass to the custom precondition.

Attribute	Description	Requirement
`name`	The name of the parameter to set.	Required
`value`	A string value to set parameter to.	Required