When you’re ready to use Liquibase, the first step whether you have an existing database or are implementing Liquibase while choosing a new database is to create a project. This guide shows you how to create a new Liquibase project using the init project command.

If you already have a working database and want to start managing it with Liquibase, the first step is to generate a changelog that captures the current state of your schema. This allows you to bring Liquibase into your existing project without disrupting your database or rebuilding anything from scratch.

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.

Once your changelog structure is set up, you’re ready to start making changes to your database and tracking those changes with Liquibase.

As your Liquibase project grows, you'll likely split your database changes into multiple changelog files for better organization. To deploy all of your changes together, you need to connect your individual changelogs using a root changelog file.

When you have generated SQL changelogs from an existing database using generate-changelog, your changesets represent the current state of your database rather than incremental changes. Unlike clean projects where you define rollback logic as you create each changeset, existing databases require you to add rollback statements to generated changesets that represent tables, constraints, and other objects that already exist.

When you have generated modeled changelogs from an existing database using generate-changelog, your changesets represent the current state of your database rather than incremental changes. Unlike clean projects where you define rollback logic as you create each changeset, existing databases require you to add rollback statements to generated changesets that represent tables, constraints, and other objects that already exist.

When starting a new project with SQL changelogs, you must manually define rollback logic for all database changes. Unlike modeled changelogs (XML/JSON/YAML), SQL changelogs do not support automatic rollback generation and require you to define how to undo each changeset explicitly. This gives you complete control over rollback logic but means every changeset that needs to be reversible must include rollback statements.

When starting a new project with XML, JSON, or YAML changelogs, you can leverage Liquibase's automatic rollback capabilities while planning for change types that require manual rollback statements. Unlike SQL changelogs, modeled changelogs support automatic rollback generation for many operations, but you still need to define manual rollback logic for certain change types.

In real-world projects, you’ll often work with several database environments, such as development, testing, staging, and production. Liquibase gives you tools to apply database changes safely and selectively across these environments. This article walks through how to use Liquibase contexts to manage multiple environments.

Even when using changelogs to manage database changes, manual updates can still happen. Liquibase allows you to capture these changes by taking a snapshot of your local environment and comparing it to a reference database. This lets you safely review and append new changes to your changelog.

You can use the JSON format snapshot file in the diff and diff-changelog commands.

Often the changelog file is so large that it causes performance issues in your editor, or there are too many merge conflicts.

The setup-liquibase GitHub action simplifies how you integrate Liquibase into your CI/CD automation pipeline. setup-liquibase installs Liquibase on your ephemeral runner of choice and lets you run any command directly in your GitHub workflow. This approach gives users who are already Liquibase and GitHub users more flexibility and full access to Liquibase's command-line capabilities. Rather than managing multiple specialized GitHub actions for different Liquibase commands, you can install Liquibase and run any command you need—whether that's update, rollback, diff, or any other operation. This gives you the flexibility to build sophisticated workflows while maintaining the simplicity of a single action to manage.