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: 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. 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 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.

Note: You can apply contexts, labels, and other Changelog and Changeset Attributes on individual changesets, not your entire changelog. For more information, see Changeset.

Related links