## Documentation

Liferay periodically releases new minor and major versions of Liferay DXP that include security and bug fixes, as well as enhancements. To upgrade to a new major Liferay DXP version increment, you must upgrade the DXP database.

Note

For large data sets in production, there are several additional considerations to perform a smooth upgrade. For example, custom code or Marketplace apps may require additional updates to continue working properly. See the guide to upgrading Liferay DXP for a comprehensive overview of the core upgrade.

Note

To update to new minor versions or service packs, instead see Updating to a New Version of Liferay DXP.

Important

Upgrading an environment in DXP Cloud requires restoring an upgraded database, and therefore involves downtime for the Liferay service to restart. Plan ahead for this downtime for production environments.

Review the following steps to perform a database upgrade:

## Install Prerequisites¶

Before beginning the upgrade procedure, satisfy the following prerequisites:

Important

Perform the following steps to download a backup (consisting of both the database and data volume) of the DXP instance currently running in your prd environment:

2. Navigate to your production environment, then select Backups from the menu.

## Extract and Import the Data¶

The next step is to extract the data from the downloaded archives and move the data to where it is needed for the upgrade.

### Extract the Data Volume¶

Perform the following steps to extract the data volume from the backup:

1. Move the downloaded .tgz archive of the data volume (named backup-lfr-<PROJECT_NAME>-prd-<BACKUP_ID>.tgz) into the LIFERAY_HOME/data folder of the Liferay bundle you extracted earlier.

2. Extract the archive by running this command:

tar -xvzf ARCHIVE_NAME.tgz


### Extract and Import the Database¶

Open a command prompt at the location of the downloaded database archive (named backup-db-<PROJECT_NAME>-prd-<BACKUP_ID>.tgz) and perform the following steps to import it to MySQL:

1. Extract the database archive:

tar -xvzf ARCHIVE_NAME.tgz


mysql -u root -ppassword

3. Create a database to import the data into, using the name of the file (minus the extension) as the database name:

create database DATABASE_NAME;

4. Import the database from the extracted .sql dump:

use DATABASE_NAME;

source DATABASE_NAME.sql;

5. Finally, disconnect from the MySQL client:

exit


The database and document library are now in place and ready for you to perform the data upgrade.

DXP bundles provide an upgrade tool that is used for data upgrades. This tool is invoked through a script included in the bundle, db_upgrade.sh.

Note

Open a command prompt within your LIFERAY_HOME/tools/portal-tools-db-upgrade-client folder. Then, run the following command:

db_upgrade.sh -j "-Dfile.encoding=UTF-8 -Duser.timezone=GMT -Xmx2048m" -l "output.log"


The upgrade tool prompts you for information about your installation before beginning the data upgrade. If you have downloaded a Liferay bundle with Tomcat, then it automatically detects some of the directories as default values.

Here is an example interaction with the upgrade tool entering this information:

Please enter your application server (tomcat):
tomcat

[ db2 mariadb mysql oracle postgresql sqlserver sybase ]
mysql

(etc.)


Once you enter the required information, the upgrade tool performs the data upgrade. When the following messages appear in the console, the upgrade is complete:

Completed Liferay core upgrade and verify processes in 64 seconds
Checking to see if all upgrades have completed... done.


Test the bundle locally to ensure the upgrade completed smoothly. You can test the instance locally by running the following command from LIFERAY_HOME/tomcat-9.x.x/bin/:

./catalina.sh run


## Compress the Document Library and Database¶

Now that your Liferay installation has been upgraded, use the following steps to prepare to upload them to your backup service

### Compress the Document Library¶

1. Open a command prompt within your LIFERAY_HOME/data folder.

2. Run the following command to compress your document library into a .tgz archive:

tar -czvf volume.tgz document_library


Important

If the data volume you downloaded contained more folders (such as a license/ folder), then add these as additional arguments after document_library.

### Export and Compress the Upgraded Database¶

1. Run the following command to perform a database dump:

mysqldump -uroot -ppassword --databases --add-drop-database lportal | gzip -c | cat > database.gz

2. Compress this file into a .tgz archive with the following command:

tar zcvf database.tgz database.gz


The database and Liferay data volume are now ready for upload to the backup service.

## Upload the Document Library and Database¶

Upload the document library and database archives to the backup service via the console:

2. Navigate to the Backups page for the appropriate environment.

3. Click Upload Backup… near the top of the screen.

4. On the Upload Backup page, expand the appropriate environment, and click the + icons for both the database and document library to upload them.

5. When both the database dump and document library are uploaded, click Initiate Upload.

Note

When the upload is complete, a new backup appears at the top of the list on the Backups page.

## Update Your Project’s Liferay Image Version¶

You must update the version of the Liferay image your environment uses so that the upgraded database works correctly.

Update these locations as needed to reflect the new version of Liferay DXP:

• The image property in liferay/LCP.json. Check the Services Changelogs for an updated image, and make sure the upgraded DXP version matches the version in the image (for example, 7.2 in liferaycloud/liferay-dxp:7.2-4.0.7).

• The liferay.workspace.docker.image.liferay property in liferay/gradle.properties. Check the Liferay DXP Docker Hub page for an image that matches your upgraded DXP version.

When both of these image versions are updated, deploy the changes to your chosen environment. This prepares the Liferay service for you to restore your uploaded backup.

## Restore the Backup¶

2. Navigate to the environment you uploaded your backup to, then click Backups from the side menu.

3. Choose a backup from the list, and then click Restore to from the Actions menu for that backup.

4. Select one of your environments to restore to from the drop-down list (e.g., your dev environment).

5. Click Restore to environment.

Note

The chosen environment will be unavailable while the the backup is being deployed.

Congratulations! You have upgraded your DXP database to the new version and deployed it to your chosen environment. You can also restore the same backup again to other environments as needed.