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.
You can 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 by modifying the database while it’s detached from your Liferay instance. 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 Upgrade Basics, you’re ready to set up the new installation and upgrade the database using the upgrade tool.
If you’re upgrading to a new Liferay Docker image and want to use the upgrade tool, use it from a Liferay Tomcat Bundle of the new Liferay version. The tool is in the bundle’s tools/portal-tools-db-upgrade-client
folder.
If you installed the new Liferay release on an application server, create a [Liferay Home]/tools/portal-tools-db-upgrade-client
folder, download the upgrade tool, and install the tool to the new folder.
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 liferay-ce-portal-tools-[version].zip . |
Setting Up a New Installation
-
Replace the new Liferay installation’s
[Liferay Home]/data
folder with the[Liferay Home]/data
folder from your backup. -
Copy your DXP activation key (Subscription) and your OSGi configuration files from your backup to the new installation.
-
If you’re upgrading to 7.2, disable search indexing using a configuration file in your new installation’s
[Liferay Home]/files/osgi/configs/
folder. For example,cd liferay-home
mkdir -p osgi/configs
echo "indexReadOnly=\"true\"" >> osgi/configs/com.liferay.portal.search.configuration.IndexStatusManagerConfiguration.config
NoteDXP/Portal 7.3+ disables/re-enables search indexing automatically.
-
If you’re using Commerce, prepare to upgrade it. See Upgrading Liferay Commerce for details.
-
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]/deploy
folder. 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
.config
file and copy it to your new[Liferay Home]/osgi/configs/
folder.ImportantIf you’re using Advanced File System Store, you must configure it with a
.config
file in the new installation before upgrading the database.Here’s an example
com.liferay.portal.store.file.system.configuration.AdvancedFileSystemStoreConfiguration.config
file with the requiredrootDir
parameter:rootDir="data/document_library"
-
Use your database vendor’s recommended JDBC driver. If you’re using MySQL, for example, set
jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver
in yourportal-ext.properties
file and replace the MySQL JDBC driver JAR your app server uses. See Database Drivers for more details.You can configure the upgrade by answering the upgrade tool prompts or by using upgrade properties files.
NoteIf you’re upgrading to a new Liferay Docker image, make sure to specify your database connection using Portal Properties files instead of Docker env variables. The Portal Properties reference lists Portal Properties that correspond with each Liferay Env variable.
-
(Optional) To enable upgrade reporting, set
upgrade.report.enabled=true
in yourtools/portal-tools-db-upgrade-client/portal-upgrade-ext.properties
file. -
(Optional) To enable upgrade log context, set
upgrade.log.context.enabled=true
in your/tools/portal-tools-db-upgrade-client/portal-upgrade-ext.properties
file.
Batch Insert Property
You can enable the batch insert property for your JDBC configuration in the portal-upgrade-database.properties
file. This improves performance by batching insert statements for faster execution. See the table below for your vendor’s property parameters. This feature is not available for DB2 and Oracle databases.
Database Provider | Property |
---|---|
MariaDB | rewriteBatchedStatements=true |
MySQL | rewriteBatchedStatements=true |
PostgreSQL | reWriteBatchedInserts=true |
SQL Server | useBulkCopyForBatchInsert=true |
The batch insert property is included in the portal-upgrade-database.properties
file for Liferay 7.4 U60+/GA60+.
Running the Upgrade Tool
Before Liferay 7.4 U82/GA82, the
db_upgrade_client.shfile was named
db_upgrade.sh.
The upgrade tool is configured via its command line interface, or by using properties files.
The db_upgrade_client.sh
script in the [Liferay Home]/tools/portal-tools-db-upgrade-client
folder invokes the upgrade tool (db_upgrade_client.bat
on Windows). The --help
option describes the tool’s usage.
./db_upgrade_client.sh --help
Here’s how to upgrade 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_client.sh -j "-Dfile.encoding=UTF-8 -Duser.timezone=GMT -Xmx4096m"
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 over 10 GB of data, allocate additional memory using the-Xmx
option.If you haven’t configured the upgrade using the upgrade properties files, the upgrade tool prompts you for some 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 completes, the upgrade starts. The tool logs each upgrade process start and completion.
ImportantThe upgrade tool only prompts you for a few configurations. Many that might be important for your application must be set in the upgrade properties file (e.g.
dl.store.impl
andmodule.framework.base.dir
). It’s a best practice to copy all properties inportal-ext.properties
over toportal-upgrade-ext.properties
. -
After the upgrade completes, check the upgrade report for any database upgrade failures, errors, or warnings. 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.
-
Copy and merge your custom Liferay Home files and application server files from your backup to the new installation. The files may include but are not limited to these:
/license/*
: Activation keys. (Subscription)/log/*
: Log files./osgi/configs/*.config
: OSGi configuration files. Only copy over your custom configuration files. Do not include any*-default.config
files generated by Liferay.portal-*.properties
: Portal properties files, such asportal-ext.properties
.- 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, check the upgrade report and see Troubleshooting Upgrades.
Next Steps
Revisit Upgrade Basics to see what’s left to upgrade.