Structure your changelog

Liquibase is designed to work in source-controlled environments. Keeping changelog files and database scripts in a source code repository means you get the standard version control functions you already use: check-in, check-out, branching, and merging.

It matters that the repository structure fits how your team actually implements and manages database changes. Get it right and teams collaborate without stepping on each other. Get it wrong and you spend your first month resolving changelog merge conflicts.

Create a changelog folder

Create a dedicated folder inside your Liquibase project to hold all your changelog files. If you already generated a changelog from an existing database, 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 usually contains no changesets of its own. Instead it includes other changelogs using include or includeAll tags.

Three reasons this matters:

• Scalability. As the project grows you will have many changelog files, split by feature, object, or release. A root changelog keeps them connected in one place.

• Deployment control. You can run liquibase update against the root file to apply everything, or update individual changelogs as needed.

• Version tracking. Source control tools track modular, organized changelogs far more cleanly than one large file.

Create the file and name it something like changelog-root, using the format you want to work in: changelog-root.xml, changelog-root.json, changelog-root.yaml, or changelog-root.sql.

Choose how to organize your changelogs

Before you add more changelogs, agree with your team how they will be organized. This is a decision, not a preference, and the two common answers suit different situations.

Organize by object. Group changelogs by database object type, so every object has its own file and its own history. Best for teams adopting Liquibase from day one, and for tracking and auditing individual objects over time.

Organize by release. Group changelogs by release, sprint, or milestone. Best for teams whose database changes were not tracked in source control before adopting Liquibase, because it starts the history from now rather than trying to reconstruct it.

You do not need to read both. Pick the one that matches your situation.

Organize changes by object · Organize changes by release

Or generate it automatically

If you are starting from an existing database, Liquibase can generate a by-object structure for you rather than you laying one out by hand. For a team with an existing schema this is often the right answer.

Generate your structure automatically

Reference

• Include and IncludeAll changelog attributes

• SqlFile change type