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. 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 that are not yet applied to your database.

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

Available attributes

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 generated SQL or used in calls to the database. The names of objects are used differently in databases. For example, Oracle converts everything to uppercase (unless quoted). There are three possible values. The default value is LEGACY.
  • LEGACY - the same behavior as in Liquibase 2.0
  • QUOTE_ALL_OBJECTS - every object gets quoted. For example: person becomes "person".
  • QUOTE_ONLY_RESERVED_WORDS - reserved keywords and invalid column names are quoted.

Available nested elements

Tag Description
preConditions Preconditions required to execute the changelog. Must be passed before the changeset will be executed. It is typically used for doing a data sanity check before doing something unrecoverable such as a dropTable. Since 1.7

Note: For more information, see Preconditions.
property The value for which to set the property.

Note: For more information, see changelog Property Substitution.
changeSet The changesets to execute.

Note: For more information, see changeset.
include Additional files containing changesets to execute.

Note: For more information, see <include> Tag.
context Context to be appended to changesets. Since 3.5

Note: For more information, see Contexts.

When the Liquibase migrator runs, it parses the changelog tag. The migrator first checks any preconditions specified. If any of the preconditions fail, Liquibase will exit 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-3.8.xsd Since 3.1. Legacy XSDs are listed on the XML Format page.

Each changeset contains the id and author tags. The id tag, author tag, classpath location, and name of the XML file create a unique identifier for the 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":  [  ]  }

The log level

To control the amount of messages that are generated when using your changelog and running Liquibase commands in the CLI, you need to use the logLevel parameter.

logLevel is an optional parameter which can be set in the liquibase.properties file or specified on the command line. The logLevel specified on the command line will override the value set in the liquibase.properties file.

Example: liquibase --logLevel=debug update

Note: For more information, see the logLevel parameter.

If you use Maven, you can control the log level of Liquibase Maven plugin with MAVEN_OPTS by passing the following command: MAVEN_OPTS=-Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG. You can also edit the log level in the ${maven.home}/conf/logging/simplelogger.properties file.

Note: To disable the logging, run MAVEN_OPTS=-Dorg.slf4j.simpleLogger.defaultLogLevel=OFF. For more information, see Configuring logging.

Related Links