Using the Database Upgrade Tool¶
The Liferay Database Upgrade Tool is a client program for upgrading Liferay DXP and Liferay Portal databases offline.
Always back up your data and installation before upgrading. Testing the upgrade process on backup copies is advised.
If you’re upgrading from 6.2 or earlier, update your file store configuration. See the Updating the File Store for more information.
Modifying a database while it’s detached from your Liferay instance allows you to tune the database for upgrade operations, prune unnecessary data (e.g., unneeded versions of Web Content, Documents, and more) to improve upgrade performance, and resolve upgrade issues. These activities are especially important for upgrading DXP and any large, critical Portal environments safely and as quickly as possible. After you’ve accounted for tuning and pruning the database and completing relevant tasks described in the Upgrade Overview, you’re ready to setup up the new installation and upgrade the database using the upgrade tool.
Setting Up a New Installation¶
Install the new Liferay release. If you’re upgrading your database for a new Liferay Docker image, install the Liferay Tomcat Bundle.
Replace the new installation’s
[Liferay Home]/datafolder with the
[Liferay Home]/datafolder from your backup.
If you’re upgrading to 7.2, disable search indexing using a configuration file in your new installation’s
[Liferay Home]/files/osgi/config/folder. For example,
echo "indexReadOnly=\"true\"" >> [Liferay Home]/files/osgi/config/com.liferay.portal.search.configuration.IndexStatusManagerConfiguration.config
If you want to upgrade your Marketplace app data along with the Liferay database upgrade, download the latest version of each app targeted for the new Liferay version and copy it to your
[Liferay Home]/deployfolder. Otherwise, you can install the apps after the database upgrade and upgrade their data as described in the Post-Upgrade Considerations.
If you’re using Advanced File System Store or Simple File System Store with a modified storage location, export your file store settings to a
.configfile and copy it to your new
If you’re using Advanced File System Store, you must configure it with a
.configfile in the new installation before upgrading the database.
Here’s an example
com.liferay.portal.store.file.system.configuration.AdvancedFileSystemStoreConfiguration.configfile with the required
Copy your DXP activation key (Subscription) and your OSGi configuration files from your backup to the new installation.
Make sure you’re using the JDBC database driver your database vendor recommends. If you’re using MySQL, for example, set
portal-ext.propertiesand replace the MySQL JDBC driver JAR your app server uses. See Database Drivers for more details.
If you’re upgrading to a new Liferay Docker image, make sure to specify your database connection using Portal Properties instead of Docker env variables. The Portal Properties reference lists the corresponding Portal Property with each Liferay Env variable.
If your installation is a Liferay Tomcat Bundle, it includes the upgrade tool at
[Liferay Home]/tools/portal-tools-db-upgrade-client. Otherwise download the tool and install it to that folder.
|DXP Edition||Download Instructions|
|Liferay DXP (Subscription)||Go to the Downloads page and select the DXP version and the Product/Service Packs file type. In the listing that appears, click Download for the Liferay DXP Upgrade Client.|
|Liferay Portal||Go to the Downloads page. In the Liferay Portal downloads menu, select Other files and click Download. The latest Liferay Portal release assets GitHub page appears. Click on
Running the Upgrade Tool¶
The upgrade tool is configured via its command line interface, or by using properties files.
db_upgrade.sh script in the
[Liferay Home]/tools/portal-tools-db-upgrade-client folder invokes the upgrade tool. The
--help option describes the tool’s usage.
Here are steps for upgrading your database with the upgrade tool:
Start the upgrade tool. Here’s an example command:
cd liferay-home/tools/portal-tools-db-upgrade-client db_upgrade.sh -j "-Dfile.encoding=UTF-8 -Duser.timezone=GMT -Xmx4096m" -l "output.log"
The command above executes the upgrade tool with the same JVM options recommended for the application server. File encoding (
UTF-8), time zone (
GMT), country, language, and memory settings (
-Xmx value) should all match your application server’s settings. For databases with >= 10 GB of data, we recommend allocated additional memory over the 4 GB default. The
-l "[file]"arguments direct upgrade tool log messages to the specified file.
If you haven’t created upgrade properties files, the upgrade tool prompts you for configuration values, and shows default values in parentheses. Here’s an example interaction:
Please enter your application server (tomcat): tomcat Please enter your application server directory (../../tomcat-9.0.17): Please enter your extra library directories (../../tomcat-9.0.17/bin): Please enter your global library directory (../../tomcat-9.0.17/lib): Please enter your portal directory (../../tomcat-9.0.17/webapps/ROOT): [ db2 mariadb mysql oracle postgresql sqlserver sybase ] Please enter your database (mysql): mariadb Please enter your database host (localhost): (etc.)
If you want to use the default value shown in a prompt, press enter.
After configuration is complete, the upgrade starts. You can monitor the log file. Log messages are reported for the start and completion of each upgrade process.
After the upgrade completes, check the log for any database upgrade failures or errors. You can use Gogo Shell commands to troubleshoot issues and finish the upgrade.
You have completed the database upgrade and resolved any issues.
Test the Upgraded Database¶
Now that the database upgrade is complete, test it.
If you’re upgrading to a new Liferay Docker image, point your image to the upgraded database and validate Liferay with the database. Please see Configuring Liferay Containers for more information.
Examine the Post-Upgrade Considerations.
/license/*: Activation keys. (Subscription)
/log/*: Log files.
/osgi/configs/*.config: OSGi configuration files.
portal-*.properties: Portal properties files, such as
Application server files: Modified scripts and configuration files.
web.xml: Portal web application descriptor.
Update the Portal properties in your new installation.
Start your server and validate Liferay with its upgraded database.
You’ve upgraded your Liferay database using the Database Upgrade Tool.
If this was a trial upgrade and you want to shorten the upgrade time, tune your database for upgrade (if you haven’t already) and remove unnecessary data from the database. Repeat this article’s steps as necessary.
If you run into issues, see Troubleshooting Upgrades.