Set up your changelog structure

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.

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.

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