<include> Tag

The <include> tag is used within your master changelog to reference other changelogs.

Uses

In Liquibase, you can break up your master changelog into more manageable pieces by creating multiple changelogs to separate your changesets in a way that makes sense for you. For example, you can separate changesets into their own files, according to features, releases, or other logical boundaries. Breaking up your changelogs can make it easier to find and manage complex database schema scripts.

The reason why you would use the <include> tag rather than using XML's built-in include functionality is that the parser sees just one large XML document. Liquibase needs to uniquely identify each changeset with an id, author, and file name.

How to use the <include> tag

  1. Create a master changelog file, if you do not have one already.

The master changelog file works as a configuration file that will hold all the references to all your other changelogs. Your master changelog file must be in XML, YAML, or JSON formats only.

Note: At this time, the <include> tag cannot be used in an SQL formatted master changelog.

  1. Add the <include> tag and file references to your master changelog.

In this example, we are using an XML master changelog with the <include> tag referencing two SQL changelogs:

Note: Your reference changelog can be SQL, XML, YAML, or JSON file types.

<?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"
	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/dbchangelog-3.8.xsd">
	<include file="com/example/news/news.changelog.sql"/>
	<include file="com/example/directory/directory.changelog.sql"/>
</databaseChangeLog>

How the <include> tag runs in a changelog

All included changelogs are run in the order they are found. So make sure that the included changelogs are completely independent or that any required changelogs are run first.

In the master changelog example above, the root changelog includes first the changes in com/example/news/news.changelog.sql then the changes in com/example/directory/directory.changelog.sql.

Preconditions should be defined in your reference changelogs, and will be evaluated by Liquibase before any changesets are ran.

About double inclusion of changelogs

Liquibase does not check for the double inclusion of changelogs in your master file. However, if you include a changelog twice, Liquibase recognizes that the changesets have already been run and will not run them again, even if you use a <runAlways> tag.

About infinite loops in changelogs

Liquibase does not check for looping changelogs in your master file. However, if you create a changelog loop like the following, you will get an infinite loop which will prevent the operation from completing:

Example: root.changelog.xml includes news.changelog.xml which includes root.changelog.xml.

Make sure to avoid infinite loops when referencing changelogs.

If you create an infinite loop, Liquibase will display the following error, and will continue to loop until the process runs out of memory:

Unexpected error running Liquibase: Unknown reason

Available attributes

Attribute Description Requirement
file Name of the file you want to import required. Required
relativeToChangelogFile File path relative to the changelog file containing the element rather than to the classpath. Default: false Optional
context

Appends a context (using an AND statement) to all contained changesets.

Note: Contexts only work with the <include> tag when referencing non-SQL files.

Example: <include file="dbchangelog_roll-forward.xml" context="DEV"/>

Optional
labels

Appends a label to all contained changesets.

Note: Labels only work with the <include> tag when referencing non-SQL files.

Example: <include file="dbchangelog_roll-forward.xml" labels="rollback_version1"/>

Optional

Related links