changelog

The root of all Liquibase changes is the changelog file. Liquibase uses a changelog to list all changes, in order, made to your database. Think of it as a ledger. It is a file that contains a record of all your database changes (changesets). Liquibase uses this changelog record to audit your database and execute any changes not yet applied to your database.

changelogs can come in one of the following formats and can be stored and versioned in your favorite source control tool:

Available attributes

Attribute Description
logicalFilePath Use to override the file name and path when creating the unique identifier of changesets. Required when moving or renaming changelogs.
objectQuotingStrategy This controls how object names are quoted in the SQL generated or used in calls to the database. Different databases do different things to the names of objects, for example Oracle converts everything to uppercase (unless quoted). There are three possible values. The default value is LEGACY.
LEGACY - Same behavior as in Liquibase 2.0
QUOTE_ALL_OBJECTS - Every object gets quoted. e.g. person becomes "person".
QUOTE_ONLY_RESERVED_WORDS - Quote reserved keywords and invalid column names.

Available nested elements

Tag Description
preConditions Pre-conditions required to execute the changelog. Read More
property Value to set property to, if not set by another means. Read More
changeSet The changesets to execute. Read More
include Additional files containing changesets to execute. Read More
context Context to be appended (using AND) to all changesets since 3.5

When the Liquibase migrator runs, it parses the changelog tag. It first checks any preconditions specified. If any of the preconditions fail, the Liquibase will exit with an error message explaining what failed. Preconditions are useful for both documenting and enforcing expectations and assumptions of the changelog writer such as the DBMS to be run against or the user the changes are run as.

If all preconditions are met, Liquibase will then begin running changeset and include tags in the order they appear in the changelog file.

The XML schema for the changelog tag is available at:

Some legacy XSDs are listed on the XML Format page.

Each changeset contains an “id” tag and an “author” tag. These tags, along with the classpath location and name of the XML file create a unique identifier for that changeset.

Empty example changelogs

SQL example

--liquibase formatted sql

XML Example

<?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-3.8.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-3.8.xsd ">  
</databaseChangeLog>

YAML example

databaseChangeLog:

JSON example

{  "databaseChangeLog":  [  ]  }