How to Add Liquibase to an Existing Database Project

Content updated September 2025

Key Takeaways

• Liquibase can be added to existing projects either by building a changelog that reflects your current database (best for long-term success) or by managing new changes going forward (fastest path).
• Review environment consistency first; Liquibase tools like diff and changeLogSync help align schemas and prevent duplicate changes.
• Successful adoption isn’t just technical—teams must adapt workflows and processes to fully benefit from standardized, automated database change management.

When teams begin exploring Liquibase, they often want to bring its automation and standardization to their existing databases. Every project has unique processes and requirements, so there are a few ways to get started. Here, you’ll see two proven approaches so you can choose what’s best for your team and project.

Bringing Liquibase to Your Existing Database Project

There are two primary ways to add Liquibase to an existing database:

• Option 1: Build a changelog that reflects your current database state. This makes it feel as if you’ve always managed changes with Liquibase. This is the recommended path for long-term success.
• Option 2: Use a snapshot from your database backup tool as a starting point and manage all changes with Liquibase going forward. This is best when you need to move quickly.

What to Consider Before You Start

Liquibase helps you bring structure and control to database changes. To set your team up for success, first take stock of your current database state. How consistent are your environments? Start by reviewing your production database, then compare it to your test and development environments to understand any differences. Liquibase’s diff command or other vendor tools can help you identify gaps across environments.

Recommended: Make It Seamless With a Changelog That Matches Your Current Database

This approach involves creating a changelog file that matches your database’s present state. You can then use this changelog to build a new database that matches your current environments—making it appear as if Liquibase has always managed your changes. While this requires more initial effort, it pays off in the long run by supporting automation, compliance, and consistent workflows.

How to Create a Changelog

• Generate a changelog automatically with the generateChangeLog command.
• After generating, review each changeset to confirm accuracy. Liquibase may not capture every database-specific detail, such as certain index or custom object configurations. Use the generated changelog as your starting point, then adjust as needed.
• If you need to capture stored procedures, triggers, or functions, make sure you have a Liquibase license key.

‍

Alternatively, some database types allow you to export a schema’s DDL to a file and use it as the initial changeset. For example, MySQL users can generate a SQL file with mysqldump and add it to version control, then reference it in your changelog with a <sqlFile> changeset. Adjust your export settings based on your requirements.

‍

Populating the Tracking Table

Once your changelog is ready, ensure that pre-Liquibase changesets only run on new databases. Liquibase uses the DATABASECHANGELOG table to track applied changes. The changeLogSync or changeLogSyncSQL command will mark all starter changesets as already run, preventing duplicate object creation.

Alternatively, you can add contexts to pre-Liquibase changesets (for example, context="legacy" ). Run Liquibase with --context=legacy for new databases and --context=non-legacy for existing ones. Another option is to add precondition onFail="MARK_RAN" tags to each changeset, so Liquibase only applies changes if needed. This approach requires more setup but simplifies deployment across all environments.

For example, if you have a <createTable tableName="person"> changeset, add:

<preconditions onFail="MARK_RAN">
    <not>
        <tableExists tableName="person"/>
    </not>
</preconditions>

‍

Learn more about using Liquibase contexts and preconditions.

The best technique to populate the tracking table depends on how similar your schemas are. In practice, teams often combine these methods. For example, generate your base changelogs from production and use changeLogSyncSQL to apply them everywhere. Then, add unreleased changesets to your changelog with preconditions so Liquibase can determine the right state for each environment.

Quick Start: Begin Using Liquibase From Today

If you want to move fast, you can start using Liquibase from this point forward. This approach skips building a changelog for existing tables—Liquibase will only track and manage new changes. Your current tables remain untouched, and you avoid the need to reconcile past changes.

‍

The main limitation is that you cannot create a new, empty database solely with Liquibase. New databases must first be restored from a pre-Liquibase backup before Liquibase manages changes going forward.

‍

If your schemas differ across environments, you may need to use preconditions or changelogSync to handle those differences. Coordinating Liquibase adoption with a release boundary can help align test and production environments.

Don’t Forget: People and Processes Matter

Adopting Liquibase—especially for existing projects—is not just a technical change. It requires integrating new workflows and adapting your team’s habits.

Many teams quickly see the value in standardized, automated change management. Others may need more time to adjust. Liquibase offers flexibility through features like SQL output, formatted changelogs, and diffChangeLog, so you can tailor adoption to your team’s needs.

If you anticipate technical or process challenges, consider starting with Liquibase on a new project first. Once your team is comfortable, expand its use to other projects. Liquibase experts have helped teams across industries bring automation, compliance, and observability to their database change management and CI/CD pipelines. Contact us for guidance tailored to your needs.

‍

Frequently Asked Questions

Q1: What’s the best way to add Liquibase to an existing project?

The most reliable method is to create a changelog that matches your current database state. This ensures consistency and long-term automation benefits.

‍

Q2: Can I start using Liquibase without migrating past changes?

Yes. You can start tracking new changes immediately, but this approach won’t allow you to build a fresh database solely from Liquibase.

‍

Q3: How do I prevent Liquibase from re-running old changesets?

Use commands like changeLogSync, contexts (e.g., legacy vs. non-legacy), or preconditions (onFail="MARK_RAN") to mark historical changes as already applied.

‍

Q4: What if my schemas differ across environments?

Liquibase’s preconditions and diffChangeLog can help align environments, while careful adoption at a release boundary ensures smoother rollout.

‍

Q5: Is adopting Liquibase just a technical change?

No—success also requires updating team workflows and processes. Training, gradual adoption, and support from Liquibase experts can make the transition easier.

‍