Upgrading the Database

Liferay’s tools and instructions facilitate upgrading DXP and Portal environments safely and quickly. Non-clustered environments that have small data sets, for example can be upgraded using a Docker image. DXP environments and Portal environments that are complex, have larger data sets, or have many customizations are upgraded using the Database Upgrade Tool. Auto upgrade can also be enabled during startup.

Important

For clustered or sharded installations, also see Upgrading Clustered and Sharded Environments

Here are the different ways you can upgrade your Liferay database:

• The Database Upgrade Tool can execute core and module database upgrades while the server is offline.

• Auto Upgrade can be enabled with a portal property for the upgrade to take place during Liferay’s startup.

• Docker images can use the following environment variable to auto-run the Database Upgrade Tool on the configured database:

  -e LIFERAY_UPGRADE_PERIOD_DATABASE_PERIOD_AUTO_PERIOD_RUN=true
  

• Gogo Shell commands can list and invoke module upgrades while the server is running. However, core database upgrades require one of the other methods.

Releases, updates, and patches have different available options for upgrading the database schema changes. The following table lists the database upgrade options for each schema change level:

Database Schema Changes	Database Upgrade Options
Module micro version (optional upgrades)	* Database Upgrade Tool * Auto Upgrade * Docker image * Gogo Shell
Module major/minor version (required upgrades)	* Database Upgrade Tool * Auto Upgrade * Docker image * Gogo Shell
Core data schema (required upgrades)	* Database Upgrade Tool * Auto Upgrade * Docker image

Database upgrades can be performed from the new installation you’re targeting or in a separate installation that’s more convenient for upgrading the database. For example, if you’re using an application server, you can upgrade the database using the new Liferay Docker image, install the new Liferay WAR and dependencies to your app server, and restart your app server to run the new Liferay version.

There are three types of DXP/Portal installations:

1. Liferay Docker image
2. Liferay Tomcat Bundle
3. Application server (app server) + Liferay WAR (WAR) + dependencies

Here are the general steps for using the database upgrade options with each installation type.

Database Upgrade for Liferay Docker Images

Here are process summaries for using a Docker image or Tomcat Bundle to perform database upgrade for a new Liferay Docker image.

Using the Database Upgrade Tool:

1. Configure the Liferay Tomcat Bundle.

2. Run the Database Upgrade Tool from the bundle.

3. When the upgrades complete successfully, configure the database on the new Docker image.

Using Docker:

1. Configure the new image.

2. Run it with the upgrade environment variable enabled.

3. When the upgrades complete successfully, configure the database on a new container of the new image (do not enable upgrades).

Database Upgrade for Liferay Tomcat Bundles

Here are process summaries for using a Docker image or Tomcat Bundle to perform database upgrade for a new Liferay Tomcat Bundle.

Using the Database Upgrade Tool:

1. Configure the new Liferay Tomcat Bundle.

2. Run the Database Upgrade Tool.

Using Docker:

1. Configure the new Docker image.

2. Run it with the upgrade environment variable enabled.

3. When the upgrades complete successfully, configure the database on the new Liferay Tomcat Bundle.

Database Upgrade for Application Server Installations

Here are process summaries for using a Docker image or Tomcat Bundle to perform database upgrade for a new Liferay DXP/Portal installation on an application server.

Using the Database Upgrade Tool:

1. Configure the new Liferay Tomcat Bundle.

2. Run the Database Upgrade Tool from the bundle.

3. When the upgrades complete successfully, install the new Liferay WAR and OSGi dependencies on the application server.

Using Docker:

1. Configure the new Docker image.

2. Run it with the upgrade environment variable enabled.

3. When the upgrades complete successfully, install the new Liferay WAR and OSGi dependencies on the application server.