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:
- changelogs in SQL Format
- changelogs in XML Format
- changelogs in JSON Format
- changelogs in YAML Format
- changelogs in Other Formats
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 .
|
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.7Note: 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.