Working with Changelogs

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 SQL files generated by Liquibase and used in calls to the database.
  • 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.

Available nested elements

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

Note: For more information, see Preconditions.

property The value for which to set the property.

Note: For more information, see Substituting Properties in Changelogs.

changeSet The changesets to execute.

Note: For more information, see Changelog Formats.

include Additional files containing changesets to execute.

Note: For more information, see include.

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 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 Changelog Formats 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.

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-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">
</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 log-level parameter.

log-level is an optional parameter that is set in the Liquibase properties file or specified on the command line. The log-level that is specified on the command line overrides the value set in the properties file.

Example: liquibase --log-level=debug update

Note: For more information, see the log-level.

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