Documentation

Database Upgrade Tool Reference

This article provides an overview of the upgrade tool within your application server.

Start the upgrade tool using the db_upgrade.sh script in the [LIFERAY_HOME]/tools/portal-tools-db-upgrade-client folder (db_upgrade.bat on Windows).

Database Upgrade Tool Usage

This command prints the upgrade tool usage:

db_upgrade.sh --help

Here are all the upgrade tool command line options:

–help or -h: Prints the tool’s help message.

–jvm-opts or -j + [arg]: Sets any JVM options for the upgrade process.

–log-file or -l + [arg]: Specifies the tool’s log file name—the default name is upgrade.log.

–shell or -s: Automatically connects you to the Gogo shell after finishing the upgrade process.

Logging Output

The -l option specifies the tool’s log file name:

db_upgrade.sh -l "output.log"

Configuring the Upgrade Tool

The core upgrade requires configuration. The simplest way is to use the upgrade tool to create your configuration files on the fly. Here’s an example interaction with the upgrade tool’s command line interface:

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.)

Note

Omitted values use the defaults displayed in the parentheses.

Manual Configuration

You can also pre-configure the upgrade tool to set more values than the tool generates. Use these files in [LIFERAY_HOME]/tools/portal-tools-db-upgrade-client/ to manually configure the core upgrade:

  • app-server.properties: Specifies the server location and libraries.

  • portal-upgrade-database.properties: Configures the database connection.

  • portal-upgrade-ext.properties: Sets the rest of the portal properties that the upgrade requires. To replicate your current DXP server, you can copy your current portal properties (except your database properties) into this file. Before using your current properties, make sure to update them for the current DXP version.

Configuring app-server.properties

Specify the following information to configure DXP’s application server:

Property Name Meaning Notes
dir The absolute path of the application server folder.
extra.lib.dirs A comma-delimited list of extra directories containing any binaries or resources to add to the class path. Use paths relative to dir.
global.lib.dir The application server's global library directory. Use a path relative to dir.
portal.dir The directory where portal is installed in your application server. Use a path relative to dir.
server.detector.server.id The ID of a supported application server. Supported IDs: jboss, jonas, resin, tomcat, weblogic, websphere, wildfly

Relative paths must use Unix style format (forward slashes) and start with a /. For example, the following properties are for Windows:

dir=D:\liferay-dxp\tomcat-9.0.17
extra.lib.dirs=/bin
global.lib.dir=/lib
portal.dir=/webapps/ROOT
server.detector.server.id=tomcat

As another example, the following properties are for Linux:

dir=/home/user/liferay
extra.lib.dirs=/liferay-portal-master/tomcat-9.0.10/bin
global.lib.dir=/liferay-portal-master/tomcat-9.0.10/lib
portal.dir=/liferay-portal-master/tomcat-9.0.10/webapps/ROOT
server.detector.server.id=tomcat

Configuring portal-upgrade-database.properties

Specify the following information to configure the database you’re upgrading. Note that these properties correspond to the JDBC portal properties you’d use in a portal-ext.properties file.

  • jdbc.default.driverClassName

  • jdbc.default.url

  • jdbc.default.username

  • jdbc.default.password

See the latest portal properties reference for a reference on these values.

Configuring portal-upgrade-ext.properties

Add all portal properties, such as portal-ext.properties file properties, from your backup. The following properties are especially important to configure the upgrade:

  • liferay.home: The LIFERAY_HOME folder.

  • dl.store.impl: The implementation for persisting documents to the document library store. This property is only mandatory if you’re using a *FileSystemStore implementation. If you updated this property in your portal-ext.properties, copy the new value here. Otherwise, set the property one of these ways:

    dl.store.impl=com.liferay.portal.store.file.system.FileSystemStore
    dl.store.impl=com.liferay.portal.store.db.DBStore
    dl.store.impl=com.liferay.portal.store.file.system.AdvancedFileSystemStore
    dl.store.impl=com.liferay.portal.store.s3.S3Store
    
  • hibernate.jdbc.batch_size: The JDBC batch size used to improve performance (set to 250 by default). This property may improve upgrade performance, but it is not required.

Example Upgrade Configurations

Here are example upgrade configuration files that you can customize and copy into [LIFERAY_HOME]/tools/portal-tools-db-upgrade-client/:

  • app-server.properties:

    dir=../../tomcat-9.0.17
    global.lib.dir=lib
    portal.dir=webapps/ROOT
    server.detector.server.id=tomcat
    extra.lib.dirs=bin
    
  • portal-upgrade-database.properties:

    jdbc.default.url=jdbc:mysql://lportal62?characterEncoding=UTF-8&dontTrackOpenResources=true&holdResultsOpenOverStatementClose=true&serverTimezone=GMT&useFastDateParsing=false&useUnicode=true
    jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver
    jdbc.default.username=root
    jdbc.default.password=
    
  • portal-upgrade-ext.properties:

    liferay.home=/home/user/servers/liferay7
    module.framework.base.dir=/home/user/servers/liferay7/osgi
    dl.store.impl=com.liferay.portal.store.file.system.FileSystemStore