Reference
Version · 5.0.4
Reference guide

include

Last updated: August 21, 2026

Use the include tag in the root changelog to reference other changelogs.

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 finding and managing complex database schema scripts easier.

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.

For more guidance on structuring your changelogs, see the Implementation Guide for your product and version.

How to use the include tag

Create a root changelog file if you do not have one already. The root changelog file works as a configuration file that holds all the references to all your other changelogs. Your root changelog can be an XML, YAML, JSON, or Formatted Mongo file.
In your root changelog, add <include> tags with paths to your other changelogs. The changelogs you include in your root changelog can be SQL, XML, YAML, or JSON files. In Liquibase MongoDB Secure 1.3.0+, you can also include formatted Mongo changelogs as JS files.

How the include tag runs in a changelog

Liquibase runs all included changelogs in the order they are found. Ensure that the included changelogs are completely independent or that any required changelogs are run first.

You should define Preconditions in your reference changelogs. Liquibase will evaluate them before running any changesets.

Double inclusion of changelogs

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

Infinite loops in changelogs

Liquibase does not check for looping changelogs in your root 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
`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: `<include file="dbchangelog_roll-forward.xml" contextFilter="DEV"/>`	Optional
`errorIfMissing`	Controls what happens if the file listed does not exist. If set to `true`, the update fails. Default: `true`.	Optional
`ignore`	Tell Liquibase to treat changesets in the included file as if it does not exist. Liquibase 3.7.0+. Default: `false`.	Optional
`labels`	Appends a label (using an `AND` statement) to all contained changesets. Example: `<include file="dbchangelog_roll-forward.xml" labels="rollback_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. Liquibase ignores this attribute when the `allow-inherit-logical-file-path` parameter is set to `false`.	Optional
`relativeToChangelogFile`	Specifies whether the file path is relative to the changelog file rather than looked up in the search path. Default: `false`.	Optional

Change history

Change	Version
Introduced SQL file support for root changelogs.	Liquibase Secure 4.28.0+
Introduced formatted Mongo file support for root changelogs.	Liquibase Secure 4.32.0+

include examples

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

--liquibase formatted sql

--include file:com/example/news/news.changelog.sql
--include file:com/example/directory/directory.changelog.sql

databaseChangeLog:
- include:
    file: com/example/news/news.changelog.sql
- include:
    file: com/example/directory/directory.changelog.sql

{
    "databaseChangeLog": [
        {
            "include": {
                "file": "com/example/news/news.changelog.sql"
            }
        },
        {
            "include": {
                "file": "com/example/directory/directory.changelog.sql"
            }
        }
    ]
}

<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:secure="http://www.liquibase.org/xml/ns/secure"
    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/secure
        http://www.liquibase.org/xml/ns/secure/liquibase-secure-latest.xsd">

	<include file="com/example/news/news.changelog.sql"/>
	<include file="com/example/directory/directory.changelog.sql"/>

</databaseChangeLog>

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

--liquibase formatted sql

--include file:com/example/news/news.changelog.sql
--include file:com/example/directory/directory.changelog.sql

databaseChangeLog:
- include:
    file: com/example/news/news.changelog.sql
- include:
    file: com/example/directory/directory.changelog.sql

{
    "databaseChangeLog": [
        {
            "include": {
                "file": "com/example/news/news.changelog.sql"
            }
        },
        {
            "include": {
                "file": "com/example/directory/directory.changelog.sql"
            }
        }
    ]
}

<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:secure="http://www.liquibase.org/xml/ns/secure"
    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/secure
        http://www.liquibase.org/xml/ns/secure/liquibase-secure-latest.xsd">

	<include file="com/example/news/news.changelog.sql"/>
	<include file="com/example/directory/directory.changelog.sql"/>

</databaseChangeLog>

Previousignore NextincludeAll

include

Uses

How to use the include tag

How the include tag runs in a changelog

Double inclusion of changelogs

Infinite loops in changelogs

Available attributes

Change history

include examples

SQL example

YAML example

JSON example

XML example