Skip to content
Star Us On GitHub

Liquibase Extension Upgrade Guides

As a platform built around extensibility, Liquibase strives to preserve API-level compatibility from release to release. However, preserving compatibility sometimes comes at a cost of not being able to use new technologies, patterns, and use cases that do not fit well into that original API structure.

In our quest to balance stability with innovation, Liquibase 4.0 introduces some API breaking changes. To ease the transition, we also included an update compatibility layer to keep existing extensions working, and give everyone time to make the (minor) extension changes required to stay fully Liquibase compatible

Impact on end-users

For most extensions, you can still run a Liquibase 3.x-designed version of the extension on Liquibase 4.0 as long as you include the liquibase-compat.jar to your classpath.

If you're using a 3.x version of an extension, download the compatibility library from Maven Central or from Github at https://github.com/liquibase/liquibase-compat/releases.

If your extension has more complexity and falls outside of the basic development patterns, it's possible that some of the functionality will be broken. The indicator of problems is the occurrence of method not found errors when performing certain operations. If this occurs, let the extension developer know.

Impact on extension authors

As an extension author, the liquibase-compat library should give you time to get your library up-to-date with Liquibase4.x so you aren't relying on theliquibase-compat library or the deprecated methods for very long.

To update your library, you will need to:

  1. Compile your extension against the 4.0 version of Liquibase without liquibase-compat.jar in your classpath
  2. Fix any compilation errors
  3. Fix any deprecated warnings
  4. Re-test functionality

By releasing a new version of your extension to work with the Liquibase 4.0, you keep your users from having to rely on the liquibase-compat library. Removing this library will reduce installation overhead and get rid of unexpected behaviors.

How to run Liquibase 4.x with pre-4.x extensions

We recognize the importance of backward compatibility to extension writers and extension users. To better support extension compatibility, we created a new liquibase-compat library for Liquibase 4.0. We intend to include new compatibility code, as changes are made to Liquibase Core, to maintain compatibility.

Here are the details about the three changes we made to this new liquibase-compat library:

  1. Introduced @Deprecated versions of classes/methods that have been shifted around
    1. We renamed the Log.debug() method to Log.fine(), added a Log.debug() method marked as deprecated that calls out to the new fine() method.
    2. We replaced how extension classes are found in Liquibase Core, so we added the old logic for locating both classes and files into the new liquibase-compat library.
  2. Added feature/functionality flags to enable old functionality
    1. Since we changed how Liquibase handled the translation between database-specific types and generic types, we added a configurable flag to change back to the old behavior.

Even though we added these tools, we are not able to promise 100% compatibility with extensions built against earlier Liquibase versions. We are striving to provide as much compatibility as possible. However, to be fully compatible with new versions of Liquibase you should build your extensions without using the liquibase-compat library and without using deprecated methods.

Available extension upgrade guides