Liferay Database Migration from 6.2 to DXP
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:
Solution:
Fix the broken articles (replace all “ ” with “ “).
update JournalArticle set content = REPLACE(content, ' ', ' ');
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 😏
Nice blog! I read your article. I really like all the points that you mentioned are interesting and helpful. Thank you for sharing this blog.
ReplyDeleteBest Social Media Marketing Services Milwaukee