includeAll

Last published July 28, 2025

Use the includeAll tag to specify a directory that contains multiple changelog files. It is used within your root changelog file to call on the directory and include all XML, YAML, and JSON files as changelog files, and all SQL files as individual changes. If you use includeAll to specify a directory that contains subdirectories, the tag also includes all files in those subdirectories.

Uses

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

If you store all of your changelog files in one directory, you can use the <includeAll> tag to reference the directory containing those files. Alternatively, you can use <includeAll> to reference a single directory containing multiple subdirectories that store all your changelog files.

For more guidance on structuring your changelogs, see Design Your Liquibase Project.

How to use the includeAll tag

  1. Create a root changelog file. The root changelog file works as a configuration file that holds all the references to other directories. Your root changelog can be an XML, YAML, JSON, or Formatted Mongo file.

  2. In your root changelog, add the <includeAll> tag with a path to the directory you want to include. Your changelogs inside the directory can include SQL, XML, YAML, or JSON files. If you use the Liquibase MongoDB Pro 1.3.0+, you can also include formatted Mongo changelogs as JS files.

How the includeAll tag runs in a changelog

All files inside the included directory are run in alphabetical order. If you use the includeAll tag, enforce a naming strategy to prevent conflicts and the need to rename and reorder files.

Infinite loops in changelogs

By default, Liquibase checks for looping changelogs in your root file. 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:

Unexpected error running Liquibase: Circular reference detected in 'com/example/changelogs/'. Set liquibase.errorOnCircularIncludeAll if you'd like to ignore this error.

It is best practice to leave the error-on-circular-include-all argument at its default setting of true to avoid a StackOverflowError.

Available attributes

Attribute

Description

Requirement

path

Name of the path you want to reference.

Required

contextFilter

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

Note: If you use Liquibase 4.23.0 or earlier, use the syntax context instead of contextFilter.

Example: <includeAll path="files" contextFilter="DEV"/>

Optional

endsWithFilter

Allows you to filter which packages are included based on their file name ending. Liquibase 4.24.0+.

Example: If you set endsWithFilter='apple.sql' on a project with the structure below, only my_pkg_1.apple.sql and my_pkg_2.apple.sql are included.

root changelog.xml packages my_pkg_1.apple.sql my_pkg_1.orange.sql my_pkg_2.apple.sql my_pkg_2.orange.sql

Optional

errorIfMissingOrEmpty

Controls what happens if the path listed does not exist or is an empty directory. If set to true, the update fails. Default: true.

Optional

filter

Allows you to specify a custom filter class to include or exclude files from the <includeAll> search. Your class must implement the IncludeAllFilter interface. See Add an IncludeAll Filter.

Optional

ignore

Tell Liquibase to treat changesets in the included files as if they do not exist. Liquibase 4.27.0+. Default: false.

Optional

labels

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

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

Optional

logicalFilePath

Liquibase 4.30.0+. Overrides the file name and path when creating the unique identifier of changesets. It is required when you want to move or rename changelogs. If specified, the logical file path cascades to included changelogs.

Optional

maxDepth

Allows you to control the maximum depth of recursion applied by includeAll, starting from the directory in path. If maxDepth=1, only files in path will be included no subdirectories are searched. Values are inclusive. If maxDepth < minDepth, Liquibase returns an error. Default: Integer.MAX_VALUE.

Optional

minDepth

Allows you to control the minimum depth of recursion applied by includeAll. If minDepth=1, search includes files from the directory in path. If minDepth=2, search excludes files from the directory in path and starts from subdirectories of path. Values are inclusive. Default: 1.

Optional

relativeToChangelogFile

Specifies whether the file path is relative to the changelog file rather than looked up in the search path. Default: false.

Optional

resourceComparator

A string containing the name of the class you want to use for sorting. Your class must implement the Comparator interface. See Add an IncludeAll Comparator.

Optional

Change history

Change

Version

Introduced SQL file support for root changelogs.

Liquibase Pro 4.28.0+

Introduced formatted Mongo file support for root changelogs.

Liquibase Pro 4.32.0+

includeAll examples

*Note: includeAll is only supported for formatted SQL changelogs in Liquibase Pro 4.28.0 and later.*

--liquibase formatted sql

--includeAll path:com/example/changelogs/
--includeAll path:liquibase/parser/core/yaml/included/