Upgrade Liquibase

Liquibase is a mission-critical component in your organization's deployment process, so any upgrades should be planned and verified carefully before rollout. The Liquibase engineering team invests heavily in our extensive test suite, but we recommend that you follow these steps when upgrading to ensure the best possible experience for your Liquibase user community.

Plan your upgrade

Planning your Liquibase upgrade should include the following elements:

  1. Review the Liquibase Release Notes. Liquibase documents all changes that may change the user experience or how changelogs are processed. You should review your existing Liquibase usage to determine if you are impacted by these changes.
    • The release notes also include notification of any third-party database drivers included in Liquibase along with a link to that driver's release notes. You should also review the release notes of any database drivers that you use in your environment.
    • You should also consider upgrading Liquibase extensions (such as the MongoDB extension) as a part of your upgrade of Liquibase core. You should also review the release notes for these extensions.
  2. Create or update your upgrade validation plan. Your validation plan for upgrading Liquibase should cover any use-cases which are critical to your organization’s use of Liquibase. While the Liquibase engineering team has an extensive test suite covering all Liquibase-maintained database drivers, you should validate the upgrade in the context of your specific environment.

    3. Here are some specific use-cases you may want to consider:

    • Running status, history, and update commands against your supported databases in a test region.
    • Performing rollbacks.
    • Running drift reports
    • Executing your Liquibase Quality Checks
    • Verifying reporting of Structured Logging to your observability tool.
    • Include coverage of Liquibase changelog patterns which are in use in your environment.
    • Validate dependencies with third-party Liquibase extensions.
    • Validate integrations into your enterprise tools such as ServiceNow or other release tracking systems necessitated by regulations in your industry.
    • Other use-cases that your team needs to handle, such as multi-schema deployments or multi-database deployments.

    You should also use the Liquibase release notes to guide the creation of additional use-cases. We recommend that you set up these test cases as jobs in your CI/CD system so that you can execute them automatically for each upgrade.

  3. Obtain the updated Liquibase release. You can obtain the Liquibase release artifacts from the download page. The Liquibase Docker image is also updated for every release. If you have extended the Liquibase Docker image, you will need to build a new version of that image to use in your testing and rollout.

    4. Note: We advise you not to use the latest tag of the Liquibase Docker image. Instead, you should reference the specific version you have tested in your upgrade process. Using the latest tag will automatically upgrade your pipelines and result in unplanned and untested upgrades.

    Warning: Liquibase versions 4.22.0 through 4.23.1 have known issues with checksums and deploying updates with native executors. For best results, please download and use the Liquibase 4.23.2 release or newer.

  4. Determine your rollout plan. In smaller environments, a simple rollout strategy of upgrading Liquibase for all pipelines at once may be sufficient. In larger environments, it is wise to perform a progressive rollout. In a progressive rollout, you upgrade Liquibase for a subset of your pipelines before applying the upgrade to the rest. By not upgrading all users simultaneously, you can identify problems before they create emergencies or failed production deployments for large numbers of teams.
  5. Notify Liquibase Support. As a part of your upgrade planning process, you should notify Liquibase support about your plan to upgrade. Please include your test plan and rollout plan. Liquibase Support will review your plan and provide feedback on it to you. Please also include your planned upgrade window so that our support team is prepared to respond appropriately. Keep in mind that responses to any support incidents will be bound by your support subscription’s service level agreement.
  6. Notify your user-community. Notify your user-community about the upgrade in advance of the upgrade window. Note any changes that may affect their usage of Liquibase.

    7. Note: You should advise your users to verify any planned production deployments by running the update-sql command well ahead of their production deployment using the update command. This will allow them to verify that their changelogs are valid and that only the expected changes will be deployed when the update command is finally run.

Upgrade rollout support activities

We recommend that you develop a post-upgrade support plan for any issues identified during the rollout of the Liquibase upgrade. We suggest the following best-practices:

  1. Establish an internal support process. This may vary according to your existing practices, but we recommend that you have an internal chat channel where users can raise concerns in real-time and where you can communicate the status of the rollout. This can be combined with a ticketing system to ensure issues are worked to resolution.
  2. Document your Liquibase Support contact plan. You should document how your team should interact with Liquibase Support. We recommend that you designate certain individuals to interact with Liquibase Support so that any issues raised include all necessary information and that your Liquibase administration team has visibility into all reported issues. You should ensure these persons have access to the Liquibase Support portal so that they can directly raise issues with the Liquibase support team.

    3. Your support plan should also note your Liquibase support level and hours of support as per your Liquibase service level agreement, along with instructions on how to open a support ticket and what information should be included. You should also provide guidance on how to open and manage an Urgent issue with Liquibase Support.

We're here for you

If you have any questions about preparing for your Liquibase upgrade or anything else, please reach out to our support team or your Customer Success Manager.

Related links