This approach tracks every object and its history of changes.

Organizing changes by objects can be useful for tracking and auditing changes and meeting industry requirements. This approach is popular for new teams working with databases and using Liquibase from day one.

Below is what a directory structure organized by objects may look like:

Best practices

Dedicate a top-level directory for all database scripts, such as sqlcode, to point to the path to the database changes in Liquibase.

Use a Liquibase root (main) changelog file inside the top-level `sqlcode` directory to define the order in which the object subdirectories will traverse. This eliminates the need for Liquibase to make multiple calls to a changelog file in each object's subdirectory. Instead, a single call is made to the root changelog file.

If your application (or data team) deploys to multiple schemas or databases, it would be desirable to create schema or database directories. Place object subdirectories inside each schema or database directory. Include a changelog file in each schema or database directory.

From the root (main) changelog file, use include tags to guide Liquibase to child changelogs located in each schema or database subdirectory. From here, use include tags again to point to child changelogs located in each object's subdirectory:

Use child changelogs in subdirectories for objects that contain changesets utilizing the `sqlFile` change type to reference specific SQL scripts for deployment.

This approach allows for the intentional selection of the scripts to be deployed and the execution order to be specified.

The sqlFile change type also allows you to handle different types of SQL, such as data, DDL, DML, stored logic scripts, and other complex SQL. It also enables you to specify a separate rollback script for each changeset.

Visit the sample GitHub repository organized by objects. Download the code if you want to use this repository structure.

Why the sqlFile recommendation matters

That last best practice is what connects your changelog layout to your rollback strategy. A separate rollback script per changeset is only possible because each changeset references a single SQL file, so the layout you pick here decides how granular your rollbacks can be later. See Implement a rollback strategy with SQL changelogs.

Generate it automatically instead

If you are starting from an existing database, you do not have to lay this out by hand. generate-changelog and diff-changelog with --object-changelogs=all build the by-object structure for you. See Generate your structure automatically.

Reference

• Include and IncludeAll changelog attributes

• SqlFile change type