Database Upgrade Tool Reference

Important

Before Liferay 7.4 U82/GA82, the db_upgrade_client.sh file was called db_upgrade.sh.

Here’s an overview of Liferay’s upgrade tool.

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

Overview

• Upgrade Tool Usage
• Configuring the Upgrade Tool

Database Upgrade Tool Usage

This command prints the upgrade tool usage:

db_upgrade_client.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_client.sh -l "output.log"

Recommended JVM Options

The upgrade tool automatically applies these default JVM parameters if not specified:

• -Dfile.encoding=UTF8
• -Duser.country=US
• -Duser.language=en
• -Duser.timezone=GMT
• -Xmx4096m

Only specify custom values when they differ from these defaults.

Since the database upgrade tool operates on your DXP database, you should also configure the upgrade tool with the same JVM options that you use for your DXP application server. If you used country and language JVM options, specify them for the upgrade tool.

While you’re at it, allocate the initial memory (-Xmx value) for the upgrade tool too. Use 4 GB at a minimum. If your DXP database has over 10 GB of data, increase the initial memory.

Using a test scenario with a 3.2 GB database and a 15 GB Document Library, specifying 8GB RAM (-Xmx8000m) was optimal:

Here is the db_upgrade_client.sh command corresponding to these settings:

db_upgrade_client.sh -j "-Xmx8000m"

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:

$ ./db_upgrade_client.sh
Please enter your Liferay home (/opt/liferay):

[ jboss tomcat weblogic wildfly ]
Please enter your application server (tomcat):

Please enter your application server directory (/opt/liferay/tomcat):

Please enter your extra library directories in application server directory (./bin):

Please enter your global library directory in application server directory (./lib):

Please enter your portal directory in application server directory (./webapps/ROOT):

[ db2 mariadb mysql oracle postgresql sqlserver ]
Please enter your database (postgresql):

Please enter your database JDBC driver class name (org.postgresql.Driver):

Please enter your database JDBC driver protocol (jdbc:postgresql://):

Please enter your database host (localhost):

(etc.)

Note

Omitted values use the defaults displayed in the parentheses.

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 configure the core upgrade manually:

• app-server.properties: Specifies the server location and libraries.
• portal-upgrade-ext.properties: Configures the database connection and all other portal properties required for upgrade. 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.

Note

The portal-upgrade-database.properties file is deprecated as of Liferay DXP 2026.Q1. All database configuration properties should be placed in portal-upgrade-ext.properties. If a portal-upgrade-database.properties exists, the upgrade tool shows a warning and ignores it.

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, tomcat, weblogic, wildfly

Relative paths must use Unix style format (forward slashes) with the ./ prefix to indicate clearly they are relative to the application server directory. For example, the following properties are for Windows:

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

As another example, the following properties are for Linux:

dir=./tomcat
extra.lib.dirs=./bin
global.lib.dir=./lib
portal.dir=./webapps/ROOT

Configuring portal-upgrade-ext.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

Liferay DXP 2026.Q1

The upgrade tool automatically optimizes JDBC URLs for batch insert operations. For PostgreSQL, MySQL/MariaDB, and SQL Server connections, the appropriate batch insert parameters are added to the connection URL automatically if not already present. In prior versions, this must be configured manually.

Note

Database configuration properties are now specified in portal-upgrade-ext.properties as of Liferay DXP 2026.Q1. The upgrade tool detects these settings automatically from your existing portal-ext.properties file and prompts you to reuse them.

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

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.

• upgrade.log.context.enabled: Set to true to see upgrade-related log lines that are tagged with an identifier. The possible identifiers are

  • {upgrade.component=portal}: for upgrade processes related to portal
  • {upgrade.component=framework}: for processes related to the upgrade framework logic
  • {upgrade.component=<bundleSymbolicName>}: for upgrade processes related to modules

To use this feature, you must copy the portal-impl/src/META-INF/portal-log4j.xml file into bundles/tomcat/webapps/ROOT/WEB-INF/classes/META-INF and rename the file to portal-log4j-ext.xml. Then find the appender definition:

<Appender name="CONSOLE" type="Console">
	<Layout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p [%t][%c{1}:%L] %m%n" type="PatternLayout" />
</Appender>

Change the definition to include %X, which tells Log4j to print the thread context information:

<Appender name="CONSOLE" type="Console">
	<Layout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p [%t][%c{1}:%L] %m %X%n" type="PatternLayout" />
</Appender>

See upgrade log context for more information.

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
  extra.lib.dirs=./bin
  global.lib.dir=./lib
  portal.dir=./webapps/ROOT
  

• portal-upgrade-ext.properties:

  jdbc.default.url=jdbc:postgresql://localhost:5432/lportal
  jdbc.default.driverClassName=org.postgresql.Driver
  jdbc.default.username=root
  jdbc.default.password=
  liferay.home=/home/user/servers/liferaydxp
  module.framework.base.dir=/home/user/servers/liferaydxp/osgi
  dl.store.impl=com.liferay.portal.store.file.system.FileSystemStore