Changelog Attributes

You can use attributes in your Changelog and in an individual Changeset to complete the following tasks:

Reference other changelogs from within a changelog
Break up your primary changelog into more manageable pieces
Specify when, how, and under what conditions to run changes in a changeset
Define the behavior of table columns

Syntax

An attribute's scope refers to what it affects—the entire changelog (global), a particular changeset (local), or an element nested inside a particular changeset, like a column. Most attributes have only one valid scope, but some can go in either the changelog or changeset, such as Preconditions.

You define some elements in the "header" of your changelog file or individual changesets. You nest other elements within the body of the changelog or individual changesets. For example, in an XML changelog:

<databaseChangeLog  objectQuotingStrategy="LEGACY">
    <changeSet  author="liquibase-docs"  id="createTable-example">
        <createTable  tableName="person"> 
            <column  name="address"  type="varchar(255)"/> 
        </createTable>  
    </changeSet>
</databaseChangeLog>

In this case, objectQuotingStrategy is an attribute whose scope is the entire changelog, changeSet is a sub-tag, and author is an attribute whose scope is a particular changeset.

Note: All changelog attributes use the camelCase format.

Changelog-scoped attributes

You can apply these attributes to your whole changelog:

Attribute Description

Attribute	Description
`context`	Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets are executed in any particular migration run. Contexts you specify in the changelog header are inherited by individual changesets. See also: `set-contexts`.
`logicalFilePath`	Overrides the file name and path when creating the unique identifier of changesets. It is required when you want to move or rename changelogs.
`objectQuotingStrategy`	Controls how object names are quoted in the SQL files generated by Liquibase and used in calls to the database. Default: `LEGACY`. `LEGACY` – The default value. Does not quote objects unless the database specifies that they must be quoted, usually including reserved words and names with hyphens. In PostgreSQL databases, mixed-case names will also be quoted. `QUOTE_ALL_OBJECTS` – Every object gets quoted. For example, `person` becomes `"person"`. `QUOTE_ONLY_RESERVED_WORDS` – The same logic as `LEGACY`, but without mixed-case objects in PostgreSQL databases.

context

Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets are executed in any particular migration run. Contexts you specify in the changelog header are inherited by individual changesets. See also: set-contexts.

logicalFilePath

Overrides the file name and path when creating the unique identifier of changesets. It is required when you want to move or rename changelogs.

objectQuotingStrategy

Controls how object names are quoted in the SQL files generated by Liquibase and used in calls to the database. Default: LEGACY.

LEGACY – The default value. Does not quote objects unless the database specifies that they must be quoted, usually including reserved words and names with hyphens. In PostgreSQL databases, mixed-case names will also be quoted.
QUOTE_ALL_OBJECTS – Every object gets quoted. For example, person becomes "person".
QUOTE_ONLY_RESERVED_WORDS – The same logic as LEGACY, but without mixed-case objects in PostgreSQL databases.

Nested elements

You can use these tags in the body of your changelog or sometimes within another nested element:

Tag	Description
`preConditions`	Preconditions required to execute the changelog. If global, must be passed before the changeset is run. Preconditions are typically used for doing a data sanity check before doing something unrecoverable such as a `dropTable`. Since 1.7
`property`	The value for which to set the property.
`changeSet`	The changesets to execute.
`include`	Additional files containing changesets to execute.
`includeAll`	An additional directory containing files with changesets to execute.
`modifyChangeSets`	Include additional files using an application's native executor.

Changeset-scoped attributes

You can apply these attributes to individual changesets:

Attribute	Description	Requirement
`author`	Specifies the creator of the changeset. Must be non-empty if the global argument `strict` is `true`. Can be empty only if `strict` is `false`.	Required
`id`	Specifies an alpha-numeric identifier. Note: If there are zeros in the id, it is best practice to put quotes around the id, such as "1.10". This allows all characters to be retained.	Required
`context`	Specifies the changeset contexts to match. Contexts are tags you can add to changesets to control which changesets will be executed in any particular migration run.	Optional
`created`	Stores dates, versions, or any other string of value without using remarks (comments) attributes. Since 3.5	Optional
`dbms`	Specifies which database type(s) a changeset is to be used for. See valid database type names on Liquibase Database Tutorials. Separate multiple databases with commas. Specify that a changeset is not applicable to a particular database type by prefixing with `!`. The keywords `all` and `none` are also available.	Optional
`failOnError`	Defines whether a database migration will fail if an error occurs while executing the changeset. Default: `true`.	Optional
`ignore`	Tells Liquibase to treat a particular changeset as if it does not exist. Default: `false`. Since 3.6 (XML/YAML/JSON). Since 4.19.0 (SQL).	Optional
`labels`	Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changesets will be executed in any migration run.	Optional
`logicalFilePath`	Overrides the file name and path when creating the unique identifier of changesets. It is required when you want to move or rename changelogs.	Optional
`objectQuotingStrategy`	Controls how object names are quoted in the SQL files generated by Liquibase and used in calls to the database. Default: `LEGACY`. `LEGACY` – The default value. Does not quote objects unless the database specifies that they must be quoted, usually including reserved words and names with hyphens. In PostgreSQL databases, mixed-case names will also be quoted. `QUOTE_ALL_OBJECTS` – Every object gets quoted. For example, `person` becomes `"person"`. `QUOTE_ONLY_RESERVED_WORDS` – The same logic as `LEGACY`, but without mixed-case objects in PostgreSQL databases.	Optional
`onValidationFail`	Controls what Liquibase does when a changeset fails validation. Values are `HALT` and `MARK_RAN`. Default: `HALT`.	Optional
`runAlways`	Executes the changeset on every run, even if it has been run before. Default: `false`.	Optional
`runInTransaction`	Specifies whether the changeset can be run as a single transaction (if possible). Default: `true`. Since 1.9. Warning: If `runInTransaction` is set to `false` and an error occurs part way through running a changeset that contains multiple statements, the Liquibase DATABASECHANGELOG table will be left in an invalid state.	Optional
`runOnChange`	Executes the changeset when you create it and each time it changes. Default: `false`.	Optional
`runOrder`	Specifies whether a changeset should be run before or after all other changesets instead of running it sequentially based on its order in the changelog. Valid values are `first` and `last`. It is typically used when you want a changeset to be always executed after everything else but don’t want to keep moving it to the end of the changelog. Setting the `runOrder` to `last` will automatically move the changeset to the final place in the changeset run order. Since 3.5 Note: `runOrder` is not supported in formatted SQL changelogs.	Optional
`runWith`	Specifies a native executor to run your SQL (`jdbc`, `mongosh`, `psql`, `sqlcmd`, `sqlpus`, or a custom executor). Default: `jdbc`.	Optional
`runWithSpoolFile`	Specifies a spool file to send output to when you deploy a particular changeset.	Optional

Sub-tags

You can nest these tags within a changeset, at the same level as the Change Type:

Tag	Description
`comment`	Specifies the description of the changeset. XML comments provide the same benefit.
`preConditions`	Preconditions required to execute the changelog. If global, must be passed before the changeset is run. Preconditions are typically used for doing a data sanity check before doing something unrecoverable such as a `dropTable`. Since 1.7
`rollback`	Specifies SQL statements or Change Type tags that describe how to rollback the changeset. For more information, see Liquibase Rollback Workflow and Automatic and Custom Rollbacks.
`rollbackSqlFile`	Liquibase Pro 4.26.0+. Formatted SQL only. Lets you specify a SQL file to roll back rather than an inline SQL statement. For more information, see Example Changelogs: SQL Format.
`validCheckSum`	Adds a checksum that is considered valid for this changeset, regardless of what is stored in the database. It is primarily used when you need to change a changeset and don't want errors thrown on databases on which it has already been run (not a recommended procedure). Special value `"1:any"` will match to any checksum and will not execute the changeset on ANY change. Since 1.7
<Any Refactoring Tag(s)>	Specifies the database change(s) to run as part of the changeset (Change Types).

Some Change Types support additional nested tags, like column, where, and whereParams. The scope of these tags is limited to the Change Type you place them in.

Other attributes

endDelimiter SQL attribute