Upgrade Basics
Liferay’s tools and instructions facilitate upgrading DXP and Portal environments safely and quickly. Non-clustered environments that have small data sets, for example can be upgraded using a Docker image. DXP environments and Portal environments that are complex, have larger data sets, or have many customizations are upgraded using the Database Upgrade Tool. Auto upgrade can also be enabled during startup.
Always back up your database and installation before upgrading. Testing the upgrade process on backup copies is advised.
Upgrading via Docker is the easiest way to upgrade a database for a small, casual Portal environment.
Before starting your upgrade, consider what may be involved. The upgrade topics fall into these categories:
- Preparation and Planning
- Upgrading Custom Development
- Migrating Configurations and Infrastructure
- Improving Upgrade Performance
- Executing the Database Upgrade
Preparation and Planning
Preparation and planning may be of little consequence for small, casual installations but is mandatory for large enterprise-level installations.
Review Available Upgrade Paths
Use the table below to determine your upgrade path, based on your version of Liferay.
| Upgrade Path | Description |
|---|---|
| Liferay Portal 6.1+ → DXP 7.4 | |
| Liferay Portal 5.x and 6.0.x → Liferay Portal 6.2 → Liferay DXP 7.4 | Support life ended for Liferay Portal 5.0, 5.1, 5.2, and 6.0 |
If you’re upgrading Liferay Portal to a new GA for the same minor version (for example, upgrading from 7.3 GA1 to GA2) and there are no data schema changes, you can start using the new GA immediately. If the schema changed, a startup message reports the new data schema version that you must upgrade your database to—invoking an upgrade with a Docker image is easiest.
If your path includes upgrading to Liferay Portal 6.2, follow the Liferay Portal 6.2 upgrade instructions first.
Some new Liferay versions rename table columns. Any virtual columns associated with these columns inhibit database upgrade and must be removed before the upgrade. After the upgrade, you can add equivalent virtual columns. See Troubleshooting Upgrades for details.
Review Deprecations and Changes to Default Settings
Features and configuration defaults may change in new versions of Liferay. See the reference section or the following articles for the most recent deprecations and changes to features and to settings:
Request an Upgrade Patch (Subscription)
Subscription
If you have a Liferay DXP subscription, update to the latest fix pack and/or request an upgrade patch to prepare for the database upgrade. File a ticket in the Help Center to start this process.
Preparing Publications
If Publications is enabled for your instance, ensure you’ve published all active publications before upgrading. After upgrading, active publications are marked as out of date and cannot be published or changed.
Keep in mind that any publication you published before upgrading cannot be reverted after the upgrade process. The Revert option is removed for all publications made on your previous Liferay version.
Prepare for Upgrading Commerce
If you’re using Commerce, prepare to upgrade it before upgrading the Liferay database. See Upgrading Liferay Commerce for details.
Update Marketplace Apps
Before upgrading the Liferay database, update your Marketplace apps for the Liferay version you’re currently on and test the updated apps. Skipping app updates can be problematic and can prevent the apps from enabling on the new Liferay version.
Do this on your current installation before database upgrade.
Your app’s latest version for your new Liferay version may have database schema changes that require data upgrades. You can upgrade the app data during or after your Liferay database upgrade.
Option 1: Install the latest apps before database upgrade and upgrade the app data automatically, as part of your database upgrade. Each database upgrade path describes app setup details.
Option 2: Install the latest apps after database upgrade and then use Gogo shell commands to upgrade the app data. The Post Upgrade Considerations describes app setup details.
Upgrading Custom Development
Plugins (e.g., themes, apps, and customizations) you’ve developed must be adapted to the new Liferay version. This can be as simple as updating dependencies or involve updating code to API changes. If you forgo updating your custom plugins, they may be disabled on the new Liferay version. Upgrading Custom Development walks through the code upgrade process.
Migrating and Updating Configurations and Infrastructure
Configurations and supporting infrastructure must be migrated and updated from your previous installation to your new one.
If you’re upgrading from 6.2 or earlier, update your file store configuration. See the Updating the File Store for more information.
If you’ve overridden the locales Portal Property, override it in the new installation before upgrading. This assures upgrading data for all of your locales.
You can wait until after database upgrade to update your other settings. See these Migrating Configurations and Properties for more information.
Improving Upgrade Performance
Upgrading large data sets can take a prohibitively long time, if you leave unnecessary data intact or forgo performance tuning. There are several ways to quicken database upgrades.
Prune Data
If your Liferay server has instances, sites, pages, or versioned content items (e.g., Web Content articles, Documents and Media files, and more) that are unnecessary, removing them can cut down upgrade time considerably. See Database Pruning for Faster Upgrades on ways to prune your database of unnecessary data.
Tune Database Performance
Adjusting your database for upgrade operations (more data writes than in production) improves database upgrade performance. See Database Tuning for Upgrades for details.
Enable Batch Insert
Enable batch insert for faster execution.
Executing the Database Upgrade
Here are two ways to upgrade your Liferay database:
-
Upgrade via Auto Upgrade can be enabled with a portal property for the upgrade to take place during startup. See Upgrade via Docker for an example of this using a Docker image. The image updates the database and then starts up using the upgraded database.
-
Using the Database Upgrade Tool. The Upgrade Tool is a client program for updating the Liferay database while it’s detached from any Liferay instance. It facilitates focusing on the upgrade process, tuning the database for upgrade operations, and pruning unnecessary data to quicken the database upgrade.
Database Upgrade Options describes upgrading the database in the above ways (and upgrading modules using Gogo Shell) with various DXP/Portal installation types.
Additional Tools
See these additional tools to assist you:
Conclusion
Once you complete the tasks outlined above, your upgrade is complete. But before using Liferay, you must re-establish desired runtime settings and undo any upgrade-specific tuning. Plus there may be applications that weren’t available on your previous Liferay version that are recommended for new Liferay production instances. See the Post-Upgrade Considerations for more information.
Now that you’re familiar with the upgrade components, you can upgrade your Liferay instance. Make sure to do preliminary tasks on your current installation, before upgrading the database. It’s common to upgrade custom plugin code and execute the database upgrade in parallel. Since, database upgrade is a popular task to start first, here are links to the two methods:
Additionally, refer to these other upgrade scenarios if they relate to your upgrade: