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, please download the compatibility library from Maven Central or from Github athttps://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, please 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 the
liquibase-compat library or the deprecated methods for very long.
To update your library, you will need to:
- Compile your extension against the 4.0 version of Liquibase without
liquibase-compat.jarin your classpath
- Fix any compilation errors
- Fix any deprecated warnings
- 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
- Introduced @Deprecated versions of classes/methods that have been shifted around
- We renamed the
Log.fine(), added a
Log.debug()method marked as deprecated that calls out to the
- 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
- We renamed the
- Added feature/functionality flags to enable old functionality
- 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.