<includeAll> tag

The <includeAll> tag allows you to specify a directory that contains multiple changelog files. It is used within your master changelog file to call on the directory and include all .xml files as changelog files, and all .sql files as individual changes.

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.

If you house all of your changelog files into one directory, you can use the <includeAll> tag to reference the directory where all those files live.

How to use the <includeAll> 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 other directories. Your master changelog file must be in XML, YAML, or JSON formats only.

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

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

In this example, we are using an XML master changelog with the <includeAll> tag referencing a directory:

Note: Your changelogs inside of the directory can be in 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">
	<includeAll path="com/example/changelogs/"/>
</databaseChangeLog>

How the <includeAll> tag runs in a changelog

All files inside of the included directory are run in alphabetical order.

If you choose to use the <includeAll> tag, make sure you have a naming strategy in place to ensure that you will never have conflicts or need to rename files to force a reordering.

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 the path com/example/changelogs/ which includes a changelog changelogloop.xml which includes root.changelog.xml.

Make sure to avoid infinite loops when referencing directories.

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
path Name of the path you want to reference. Required
errorIfMissingorEmpty Controls what happens if the path listed does not exist or is an empty directory. Default: false. If set to true, the update will fail.  
relativeToChangelogFile File path relative to the changelog file containing the element rather than to the classpath. Default: false. Optional
resourceComparator A string containing the name of the class you want to use for sorting.  
filter A class name that allows you to create custom filters.  
context

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

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

Example: <includeAll path="files" context="deploy_version1"/>

Optional

Related links