Upgrading Your Database Tables

Upgrading Your Database Tables

Available Liferay DXP 7.4 U10+ or Liferay Portal 7.4 GA14+

An upgrade of your application may require making changes to your database tables. Liferay’s Upgrade framework makes it easy to make these changes. Deploy the sample project to see this upgrade process. See Creating Upgrade Processes for Modules for previous versions of Liferay.

Deploy Version 1.0.0

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u86

Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

  1. Download and unzip Upgrading Your Database Tables.

    curl https://resources.learn.liferay.com/dxp/latest/en/building-applications/data-frameworks/upgrade-processes/liferay-p5d2.zip -O
    unzip liferay-p5d2.zip
  2. Move into the 1.0.0 directory, build and deploy.

    cd 1.0.0
    ../gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)

    This command is the same as copying the deployed jars to /opt/liferay/osgi/modules on the Docker container.

  3. Confirm the deployment in the Liferay Docker container console.

    STARTED com.acme.p5d2.api_1.0.0 [1030]
    STARTED com.acme.p5d2.service_1.0.0 [1031]
  4. If you are using an external database, verify the table columns for the app. For example, for MySQL:


    Verify the table columns in your database.

Upgrade to 2.0.0

  1. Now deploy the 2.0.0 version. Move into the 2.0.0 directory, build and deploy.

    cd 2.0.0
    ../gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
  2. Log into Liferay and navigate to the Gogo shell console at Control PanelGogo Shell.

  3. Verify that the 2.0.0 upgrade is available by entering the command upgrade:list com.acme.p5d2.service.

  4. Run the upgrade by entering the command upgrade:execute com.acme.p5d2.service. The Gogo shell console shows the completed upgrade process.

    Execute the upgrade in Gogo shell.

  5. You can verify that the table columns have been updated in the database. For example, for MySQL:


    Verify the table columns have been updated.

Examine the Code

The example project demonstrates a simple change of the following table columns:

Before After Comment
able (type: long) able (type: date) The column datatype is changed.
baker (type: boolean) - The column is dropped
foo (type: string) bar (type: string) The column name is changed.
- charlie (type: string) A new column is added.

Compare the service.xml column definitions of 1.0.0 with 2.0.0

Create an UpgradeStepRegistrator Class

Create a UpgradeStepRegistrator class that implements the UpgradeStepRegister interface.

@Component(service = UpgradeStepRegistrator.class)
public class P5D2EntryUpgrade implements UpgradeStepRegistrator {

	public void register(Registry registry) {
		registry.register("1.0.0", "2.0.0", new P5D2EntryUpgradeProcess());


Override the register method to implement the app’s upgrade registration. Make sure to use the @Component annotation and identify it as a UpgradeStepRegistrator.class service.

Create an UpgradeProcess Class

Create an UpgradeProcess class that extends the base class.

public class P5D2EntryUpgradeProcess extends UpgradeProcess {

	protected void doUpgrade() throws Exception {
		alterColumnName("P5D2_P5D2Entry", "foo", "bar VARCHAR(75) null");
		alterColumnType("P5D2_P5D2Entry", "able", "DATE");
		alterTableAddColumn("P5D2_P5D2Entry", "charlie", "VARCHAR(75) null");
		alterTableDropColumn("P5D2_P5D2Entry", "baker");


Override the doUpgrade() method with instructions to modify your table. The following operations are available:

Function Description
alterColumnName Change the column name
alterColumnType Change the column datatype
alterTableAddColumn Add a new column
alterTableDropColumn Remove a column

alterTableDropColumn does not work in MariaDB. This is a known bug. Follow the previous guidelines instead.

Re-run Service Builder after making your changes. You are now ready to build an deploy your upgrade.

Managing Complex Upgrades

If your upgrade is complex with many steps, consider using the getPreUpgradeSteps() and getPostUpgradeSteps() methods in your UpgradeProcess class. This approach provides more control over the upgrade process. Each upgrade step is given a different schema version in the Release_ table for easier debugging. If a step fails and you must re-run the upgrade, the upgrade process automatically checks and restarts the upgrade from the latest point of failure.

For example, Liferay’s OpenIdConnectSessionUpgradeProcess utilizes this feature.

In this example, the getPreUpgradeSteps() runs first, which involves a simple step to add a new column. The doUpgrade() method involves populating the new column. If the doUpgrade() method fails, a developer can debug, make the necessary changes, and re-run the upgrade. The process recognizes the first step succeeded and automatically moves on to the next step.

Note, to utilize the upgrade steps, import import com.liferay.portal.kernel.upgrade.UpgradeStep class into your upgrade process.