A Step-by-Step Guide to Liferay Portal Upgrade: From Planning to Execution

Upgrade Basics

Liferay offers a range of tools to facilitate the upgrade process, including the Docker image for simpler environments and the Database Upgrade Tool for more complex scenarios. Auto upgrade can also be enabled during startup for certain cases.

Note: Upgrading via Docker is the easiest way to upgrade a database for a small, casual Portal environment.

Preparation and Planning

Proper preparation is essential, especially for large enterprise-level installations. Here's what you need to consider:

Review Available Upgrade Paths

Based on your current Liferay version, choose the right upgrade path:

When upgrading Liferay Portal to a new GA within the same minor version (e.g., from 7.2 GA1 to GA2), and there are no data schema changes, you can start using the new GA immediately. However, if there are schema changes, a startup message will notify you of the new data schema version required for the database upgrade. In this case, using a Docker image to invoke the upgrade is the simplest approach.

Upgrading Custom Moduals

If you’ve developed custom plugins such as themes or MVC modauls, they must be adapted to the new Liferay version. This may require updating dependencies or addressing API changes. Plugins that are not updated may be disabled after the upgrade.

Migrating Configurations and Infrastructure

Your configurations and supporting infrastructure must be migrated and updated for the new installation. If upgrading from Liferay 6.2 or earlier, updating your file store configuration is crucial for a smooth upgrade.

Important: If you’ve overridden the locales Portal Property, ensure this is done in the new installation before upgrading.

Improving Upgrade Performance

Upgrading large datasets can be time-consuming, but several techniques can help speed up the process:

Database Pruning for Faster Upgrades

The more data you have, the longer your data upgrade takes. Unneeded site data is a common occurrence. Pruning the database of unneeded data improves upgrade process performance.

For example, sites may store many unused versions of Web Content articles or Documents and Media files. If you’re done revising them and don’t need the intermediate revisions, you can safely remove them. This saves space and upgrade time.

Here are the database pruning topics:

• Removing Duplicate Web Content Structure Field Names: Ensure that there are no duplicate field names in Web Content structures before upgrading.
• Finding and Removing Unused Objects: Identify and remove unused objects from the database to reduce upgrade time.
• Testing with a Copy of the Pruned Database: Always test your instance with a copy of the pruned database to ensure everything is functioning correctly.
• Removing Obsolete Data: Data cleanup tools are available in versions 7.3+ and 7.4+ to remove obsolete data from modules.

Removing Duplicate Web Content Structure Field Names

If you’ve used Web Content Management extensively, you might have structures without unique field names. Remove duplicate field names before upgrading to avoid errors like:

com.liferay.dynamic.data.mapping.validator.DDMFormValidationException$MustNotDuplicateFieldName: The field name page cannot be defined more than once

Removing Unused Objects

Your database may have leftover data from unused objects. You should identify unused objects and remove them using Liferay's UI or API. Avoid using SQL directly, as it may miss object relationships and cause performance problems.

Common Object Types Worth Checking

• Sites: Remove sites you don’t need, which will also remove related objects such as layouts and asset entries.
• Instances: Remove unused instances to optimize upgrades.
• Intermediate Web Content Versions: Remove versions of Web Content articles you no longer need.
• Document Versions: Delete unnecessary document versions to save space.
• Roles: Remove any roles that are no longer needed to reduce upgrade time.
• Users: Remove inactive users to optimize performance.

Published Staged Changes and Turn Staging Off

If local/remote staging is enabled, make sure to publish all changes before upgrading and turn off staging afterward.

Testing with a Copy of the Pruned Database

Test your instance with the pruned database to ensure that nothing important has been mistakenly removed.

Database Tuning for Upgrades

Performing an upgrade impacts the database differently from daily production use. Tuning the database for the upgrade process is essential for optimizing performance.

Here are some database tuning tips:

• Deactivate data integrity measures to improve performance.
• Minimize transaction logging, as it's insignificant for upgrades.
• Use asynchronous commit-related I/O operations.
• Reduce connection latency between the upgrade tool and the database server.

Batch Insert Property

You can enable the batch insert property in your JDBC configuration to improve performance by batching insert statements for faster execution.

The sections below provide links to vendor-specific information on how to tune each database as described.

IBM DB2: Please consult IBM’s official DB2 documentation.

MariaDB: Turn off InnoDB double-write and set the InnoDB flush log at transaction commit to 0.

Microsoft SQL Server: Set transaction durability to FORCED.

MySQL: Turn off InnoDB double-write and set the InnoDB flush log at transaction commit to 0. Deactivate query cache by setting the query cache size to 0.

Oracle Database: The default configuration works well. It configures asynchronous I/O to disk automatically.

PostgreSQL: Turn off synchronous commits and set the write ahead log writer delay to 1000 milliseconds.

This content is referenced form Liferay Learn.

Executing the Database Upgrade

There are two primary methods for upgrading your Liferay database:

• Auto Upgrade: This can be enabled with a portal property to upgrade the database automatically during startup.
• Database Upgrade Tool: This tool facilitates the upgrade process by detaching the database from the Liferay instance, allowing you to perform tuning and pruning for optimal performance.

Additional Tools

There are additional tools available to assist with the upgrade process:

• Upgrade Report: Provides insights into the upgrade process.
• Upgrade Log Context: Helps monitor and troubleshoot the upgrade process.
• Monitoring Upgrades with MBeans: Offers detailed upgrade monitoring capabilities.