includeAll

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 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 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.
  2. Note: Your root changelog must be an XML, YAML, or JSON file. The <includeAll> tag cannot be used in a formatted SQL or formatted Mongo root changelog.

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

    In this example, we are using an XML root changelog with two <includeAll> tags referencing one directory each:

    <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">
    
    	<includeAll path="com/example/changelogs/"/>
    	<includeAll path="liquibase/parser/core/yaml/included/"/>
    
    </databaseChangeLog>

    In this example, we are using a YAML root changelog with two <includeAll> tags referencing one directory each:

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

    In this example, we are using a JSON root changelog with two <includeAll> tags referencing one directory each:

    {
        "databaseChangeLog": [
            {
                "includeAll": {
                    "path": "com/example/changelogs/"
                }
            },
            {
                "includeAll": {
                    "path": "liquibase/parser/core/yaml/included/"
                }
            }
        ]
    }

How the includeAll tag runs in a changelog

All files inside of 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 a best practice to leave the error-on-circular-include-all argument at its default setting of true in order to avoid a StackOverflowError.

Available attributes

Attribute Description Requirement
path Name of the path you want to reference. Required
context

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

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

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

Optional
endsWithFilter

Allows you to filter which packages are include 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 and Add an IncludeAll Comparator for more information. Optional
labels

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

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

Optional
maxDepth Allows you to control the maximum depth of recursion applied by includeAll, starting from the directory in path. If maxDepth=0, no subdirectories are searched. Values are inclusive. If maxDepthminDepth, Liquibase returns an error. Default: Integer.MAX_VALUE. Optional
minDepth Allows you to control the minimum depth of recursion applied by includeAll. If minDepth=0, search starts from the directory in path. If minDepth=1, search starts from subdirectories of path. Values are inclusive. Default: 0. 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. Optional

Related links