Using Upgrade Processes

Liferay DXP 7.4 U10+/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.

Note

For earlier versions of Liferay, see Using Upgrade Processes in Earlier Versions.

Deploy Version 1.0.0

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q2.11

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:

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

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.

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]

If you are using an external database, verify the table columns for the app. For example, for MySQL:
```
SHOW COLUMNS FROM P5D2_P5D2Entry;
```

Upgrade to 2.0.0

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)
```
Log into Liferay and navigate to the Gogo shell console at Control Panel → Gogo Shell.
Verify that the 2.0.0 upgrade is available by entering the command upgrade:list com.acme.p5d2.service.
Run the upgrade by entering the command upgrade:execute com.acme.p5d2.service. The Gogo shell console shows the completed upgrade process.
You can verify that the table columns have been updated in the database. For example, for MySQL:
```
SHOW COLUMNS FROM P5D2_P5D2Entry;
```

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 issue. To work around this, you can use 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.

Capability: