Liferay Database Migration: from 6.2 to DXP

Overview

This article describes the steps required to migrate the database from Liferay 6.2 to Liferay 7.3 / DXP.

Migration Steps

1. Create a dump for 6.2 database

mysqldump -uroot -p1 liferay_62 > backup.sql

2. Create database for Liferay DXP:

create database liferay_dxp character set utf8;

3. Load dump file to DXP database:

mysql -uroot -p1 liferay_dxp < backup.sql

4. Specify database connection properties in portal-setup-wizard.properties for Liferay DXP:

jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver

jdbc.default.url=jdbc:mysql://localhost:3306/liferay_dxp?serverTimezone=Europe/Istanbul&useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false

jdbc.default.username=root

jdbc.default.password=1

5. Copy the data/document_library folder from Liferay 6.2 to DXP.

6. Disable indexing.

Create file osgi/config/com.liferay.portal.search.configuration.IndexStatusManagerConfiguration.config with content indexReadOnly="true"

7. Run the migration tool.

7.1. Navigate to bundles/tools/portal-tools-db-upgrade-client folder in Liferay DXP.

7.2. Update app-server.properties file:

dir=../../tomcat-9.0.37

extra.lib.dirs=/bin

global.lib.dir=/lib

portal.dir=/webapps/ROOT

server.detector.server.id=tomcat

7.3. Update portal-upgrade-database.properties file:

jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver

jdbc.default.url=jdbc:mysql://localhost:3306/liferay_dxp?serverTimezone=Europe/Istanbul&useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false

jdbc.default.username=root

jdbc.default.password=1

7.4. Update portal-upgrade-ext.properties file:

liferay.home=../../

module.framework.base.dir=../../osgi

7.5. Make sure, build number is 62xx before the migration:

7.6. Run the database upgrade:

./db_upgrade.sh

Wait until database migration is finished. 

Make sure, buildNumber is 73xx:

8. Enable indexing.

Remove the IndexStatusManagerConfiguration.config file created at step 6.

9. Start Liferay DXP.

Note: instead of steps 6-8, you can run step 9 (Start Liferay) immediately after step 5. Upgrade process should start automatically during Liferay startup. 

This approach may be slower, but it will give the possibility to debug and find the migration issues.

Known Issues

1. Failed to upgrade journal service due to null category name

Stacktrace:

2021-10-20 10:48:55.485 ERROR [main][UpgradeStepRegistratorTracker:144] Failed upgrade process for module com.liferay.journal.service

com.liferay.portal.kernel.upgrade.UpgradeException: com.liferay.asset.kernel.exception.AssetCategoryNameException: Category name cannot be null for category 0 and vocabulary 40994802

  at com.liferay.portal.kernel.upgrade.UpgradeProcess.upgrade(UpgradeProcess.java:109)

Reason:

During migration to 7.x Liferay tries to create an asset category for each distinct type of web content (JournalArticle.type_ field).

If type is null/blank - category can’t be created and exception occurs.

Solution:

Update blank types with the default ‘general’ type before running the migration:

update JournalArticle set type_ = 'general' where type_ = '';

2. Failed to upgrade journal service due to missing companyId

Stacktrace:

2021-10-20 15:08:00.453 ERROR [main][UpgradeStepRegistratorTracker:144] Failed upgrade process for module com.liferay.journal.service

com.liferay.portal.kernel.upgrade.UpgradeException: java.lang.ArrayIndexOutOfBoundsException: 0

   at com.liferay.portal.kernel.upgrade.UpgradeProcess.upgrade(UpgradeProcess.java:109)

   ...

   at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:473)

Caused by: java.lang.ArrayIndexOutOfBoundsException: 0

   at com.liferay.portal.util.PortalInstances.getDefaultCompanyId(PortalInstances.java:203)

   at com.liferay.portal.util.PortalImpl.getDefaultCompanyId(PortalImpl.java:2145)

   at com.liferay.commerce.product.internal.model.listener.AssetCategoryModelListener.onAfterCreate(AssetCategoryModelListener.java:53)

   ... 268 more

Workaround:

Run migration in Debug mode, stop on conditional breakpoint, and fix the _companyIds array

3. Failed to upgrade journal service due to DocumentException

Stacktrace:

ERROR - Failed upgrade process for module com.liferay.journal.service

com.liferay.portal.kernel.upgrade.UpgradeException: com.liferay.portal.kernel.xml.DocumentException: Error on line 29 of document  : The entity "nbsp" was referenced, but not declared.

at com.liferay.portal.kernel.upgrade.UpgradeProcess.upgrade(UpgradeProcess.java:109)

Link:

https://liferay.dev/ask/questions/portal/nbsp-error-while-running-db-upgrade-script-from-6-2-to-7-2-1

Solution:

Fix the broken articles (replace all “&nbsp;” with “ “).

update JournalArticle set content = REPLACE(content, '&nbsp;', ' ');

4. Failed to upgrade layout admin web due to LocaleException

Stacktrace:

2021-10-20 21:21:09.708 ERROR [pipe-upgrade:execute com.liferay.journal.service][UpgradeStepRegistratorTracker:144] Failed upgrade process for module com.liferay.layout.admin.web

com.liferay.portal.kernel.upgrade.UpgradeException: com.liferay.portal.kernel.exception.LocaleException

at com.liferay.portal.kernel.upgrade.UpgradeProcess.upgrade(UpgradeProcess.java:109)

...

at java.lang.Thread.run(Thread.java:748)

Caused by: com.liferay.portal.kernel.exception.LocaleException

at com.liferay.portal.service.impl.GroupLocalServiceImpl.validateLanguageIds(GroupLocalServiceImpl.java:4946)

at com.liferay.portal.service.impl.GroupLocalServiceImpl.updateGroup(GroupLocalServiceImpl.java:3841)

...

at com.liferay.layout.admin.web.internal.upgrade.v_1_0_2.UpgradeLayoutSetTypeSettings.updateRobots(UpgradeLayoutSetTypeSettings.java:98)

at com.liferay.layout.admin.web.internal.upgrade.v_1_0_2.UpgradeLayoutSetTypeSettings.doUpgrade(UpgradeLayoutSetTypeSettings.java:41)

at com.liferay.portal.kernel.upgrade.UpgradeProcess.upgrade(UpgradeProcess.java:104)

... 150 more

Reason:

This issue may happen due to wrong locale configuration (e.g. using EN_GB locale instead of EN_US).

Solution:

Replace EN_GB locale with EN_US in portal settings before the upgrade.

If this does not help - run this query to fix the locale issue:

UPDATE Group_ SET typeSettings = replace(typeSettings, 'en_GB', 'en_US');

Checking the upgrade

To check the upgrade status and run upgrade manually we can use Gogo shell, see:

https://help.liferay.com/hc/en-us/articles/360017897392-Gogo-Shell-Commands-for-Module-Upgrades

• upgrade:check - check modules, available for upgrade;

• upgrade:execute <module-name> 

Check if there are still modules to upgrade, and run the upgrade process. Fix the upgrade issue (if any), and run the upgrade process again, until all the modules are upgraded successfully.

Enjoy 😏