Set up your changelog structure
Last updated: July 14, 2025
After generating your initial changelog, organizing your changelogs properly is essential to keep your project maintainable as it grows. Follow these steps to set up a root changelog and organize your nested changelogs for scalability and easier collaboration.
Before you begin
Make sure you've installed Liquibase and can run
liquibase
from your command line.Connect your database to Liquibase. You'll need to follow the integration guide for your specific database.
If you have an existing database, you'll also need to generate your changelog from your existing database.
Procedure
Create a changelog folder.
Create a dedicated folder inside your Liquibase project to store all your changelog files. This keeps your project organized.
Note: If you have a generated changelog file, you'll want to move it into this folder.
Set up your root changelog.
The root changelog is a master file that organizes and references all your other changelog files. It doesn't usually contain any changesets directly—instead, it includes other changelog files using include
or includeAll
tags.
Why this matters:
Scalability: As your project grows, you'll have multiple changelog files for different features, database objects, or releases. A root changelog keeps everything connected in one place.
Deployment control: You can run
liquibase update
on the root file to apply all changes, or update individual changelogs as needed.Version tracking: It helps source control tools (like Git) track changes more easily when changelogs are modular and organized.
Create the file and give it a name, such as changelog-root. Be sure to use the file extension type you'd like to use, such as changelog-root.xml
, changelog-root.json
, changelog-root.yaml
, or changelog-root.sql
.
Choose how to organize your changelogs.
Before you begin to add more changelogs to your project, it is important that you and your team get a plan in place for how these changelogs are going to be organized. A few common ways to organize changelogs are by object, release, or version.
Organize by object
Group changelogs based on database object type (e.g., tables, views, indexes).
This helps developers avoid editing the same file and makes object-specific changes easier to trace.
Example structure:
com
example
db
changelog
changelog-root.yaml
changelog-index.sql
changelog-procedure.sql
changelog-table.sql
changelog-view.sql
In this example, we have a root changelog called changelog-root.yaml
which contains include
tags referencing changelog-index.sql
, changelog-procedure.sql
, changelog-table.sql
, and changelog-view.sql
.
Alternatively, you can create directories for each type of object, each containing one or more changelogs per particular database object:
com
example
db
changelog
changelog-root.yaml
changelog-indexes
my-favorite-index.sql
that-other-index.sql
changelog-tables
employees.sql
customers.sql
Organize by release
Group changelogs by release, sprint, or milestone.
This approach keeps all changes related to a release together, which can make deployments easier to coordinate.
Example structure:
com
example
db
changelog
changelog-root.yaml
changelog-1.0.sql
changelog-1.1.sql
changelog-2.0.sql
In this example, we have a root changelog called changelog-root.yaml
which contains include
tags referencing changelog-1.0.sql
, changelog-1.1.sql
, and changelog-2.0.sql
.
Alternatively, you can create directories for each major release (or other release group), each containing one or more changelogs per minor release:
com
example
db
changelog
changelog-root.yaml
changelog-1.X
changelog-1.0.sql
changelog-1.1.sql
changelog-2.X
changelog-2.0.sql