Changelog
The root of all Liquibase changes is the changelog file. Liquibase uses a changelog to sequentially list all changes made to your database. Think of it as a ledger. Liquibase uses this changelog record to audit your database and execute any changes that are not yet applied to your database. You can store and version your changelog in any source control tool.
An individual unit of change in your changelog is called a Changeset. When you want to modify your database, simply add a new changeset and specify its operation as a Change Type. For example, you may add a changeset to create a new table, and another changeset to drop a primary key.
You can use Contexts, Labels, and Preconditions in your changelog to precisely control which changesets run—and in which environments. You can also include other changelogs in a main changelog to keep organized.
When you run the update command, Liquibase deploys the changes you specify in your changelog to your database. To learn more about using changelogs and changesets, see Introduction to Liquibase.
File formats
You can write your changelog files in the SQL, XML, YAML, and JSON formats. Click the drop-downs to see examples.
Tip: The following examples demonstrate the structure of a changelog using generic terms. For examples that use real change types and preconditions, see the "Example Changelogs" pages linked in the drop-down tabs.

Read more: Example Changelogs: SQL Format.
--liquibase formatted sql
--precondition-name precondition-attribute:value
--changeset author:id
changetype name (
changetype attributes
);
--other element

Read more: Example Changelogs: XML Format.
<?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:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
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-latest.xsd
http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">
<preCondition>
<preConditionName preConditionAttribute="value">
</preCondition>
<changeSet id="value" author="value">
<changeTypeName changeTypeAttribute="value">
<nestedElementName elementAttribute="value">
</changeTypeName>
</changeSet>
</databaseChangeLog>

Read more: Example Changelogs: YAML Format.
databaseChangeLog:
- preCondition:
- preConditionName:
preConditionAttribute: value
- changeSet:
id: value
author: value
changes:
- changeTypeName:
changeTypeAttribute: value
nestedElementGroup:
- nestedElementName:
nestedElementAttribute: value

Read more: Example Changelogs: JSON Format.
{
"databaseChangeLog": [
{
"preCondition": [
{
"preConditionName": {
"preConditionAttribute": "value"
}
}
]
},
{
"changeSet": {
"id": "value",
"author": "value",
"changes": [
{
"changeTypeName": {
"changeTypeAttribute": "value",
"nestedElementGroup": [
{
"nestedElementName": {
"NestedElementAttribute": "value"
}
}
]
}
}
]
}
}
]
}
For additional formats, see Example Changelogs: Other Formats.
Runtime logic
When you run a database update, the Liquibase migrator parses the changelog tag. The migrator first checks any preconditions specified. If any of the preconditions fail, Liquibase exits with an error message explaining what failed. Preconditions can be typically used for both documenting and enforcing expectations or assumptions. For example, you can specify the DBMS to be run against the changelog or the user you should log in to run changes.
If all preconditions are met, Liquibase will begin running changeset and include
tags in the order they appear in the changelog file.
Note: The XML schema for the changelog tag is available at: http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd. The version of the XSD can be set to either latest
to match your current version of Liquibase, or "latest" can be replaced with a specific version, like http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.12.xsd. Legacy XSDs are listed on the XML Format page.
Each changeset contains the id
and author
tags. The id
tag, author
tag, search path location, and name of the XML file create a unique identifier for the changeset.
Attributes
You can apply these attributes to your whole changelog:
Attribute | Description |
---|---|
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:
|
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. Must be passed before the changeset is run. It is typically used for doing a data sanity check before doing something unrecoverable such as a |
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. |
Note: You can apply contexts, labels, and other Changelog and Changeset Attributes on individual changesets, not your entire changelog. For more information, see Changeset.