Documentation

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-u22

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://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)
    

    Note

    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:

    SHOW COLUMNS FROM P5D2_P5D2Entry;
    

    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:

    SHOW COLUMNS FROM P5D2_P5D2Entry;
    

    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.

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.

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

Warning

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.