Liferay Migration Process from 4.x to 6.x

Introduction:


I am considering JBoss bundled Liferay Portal.

Liferay is a portal framework which can be used to create and manage web portals in a much easier way than any other existing portal framework. Liferay has been evolving since they released Liferay 4.2.3 Portal with many user friendly features which soon started getting popular. Today the released version of Liferay is Liferay 6.1 with many more enhancements and new features which makes Liferay the most downloaded open source software of all times.

As Liferay was evolving there was need to support migration from an old version to any other version above this version. So Liferay came up with migration APIs to facilitate the migration process.

This document will describe approach and guidelines of how to understand and perform database migration from Liferay 4.2.3 to Liferay 6.1.

As per the recommendations from Liferay regarding database migration, we need to perform the migration in 3 stages stated below:

Stage I - Migration from Liferay 4.2.3 to Liferay 5.2.3
Stage II - Migration from Liferay 5.2.3 to Liferay 6.0
Stage III - Migration from Liferay 6.0 to Liferay 6.1

Prerequisites:

In order to initiate the migration following are the prerequisites:
1. Liferay 4.2.3 Database Dump
2. Liferay 5.2.3 portal bundled with JBoss
3. Liferay 6.0 portal bundled with JBoss
4. Liferay 6.1 portal bundled with JBoss
5. Access to SQL Query Browser, for example if DB is MySQL then we need MySQL Query Browser

Methodology:

Step I

Take the DB dump and import the dump to another database. For Example , if the database name of Liferay 4.2.3 is "ABC" then take a backup as ABC.sql. Create a database with name "XYZ" and import ABC.sql into this database.

This will create a copy of the LIVE database, this step is very important because doing migration on the Live DB directly is risky and not recommended.

Step II

Once you have the copy of the Database, next we need to set up a vanilla Liferay 5.2.3 bundled with JBoss on the local system. As we know we need to create portal-ext.properties file to configure Liferay with a database., so once the file is created we need to mention the database name of the one which needs to be migrated. In this case it will be XYZ.

Once you have provided the details to connect to the DB, simply start the server. Liferay portal will identify by itself that the database to which is connected right now is of old version and based on the version number respective Upgrade process will be initiated.




Step III

In the upgrade process based on the version schematic changes are initiated on the DB. This will involve temporary back up of tables, then creation of new table structure and inserting the data into the table.

Once the upgrade process is completed then Verification Process is initiated. This process actually verifies that the data which is present in the table is as per the requirements of Liferay 5.2.3.

Once the data gets migrated to desired version try logging into the server and cross check the data which got migrated with original database.

By following the steps mentioned above migration process can be carried out for the other two stages.

Points to Remember:

1. If using a windows machine where the migration will be carried out then start the server within the command prompt using "catalina.bat run" command. This will help you in checking the logs even if there is a System Exception which caused the server to shutdown.

2. During the migration process if any exception occurs resulting into system error leading to shutdown of server, then check from logs to which version Liferay was upgraded to. For example, if in the logs its mentioned that Upgrade successful to 5.0.01 version then execute the following query for "release_" table in the database.

"update XYZ.release_ set build =5001 where releaseId=1"

3. By executing this query we have updated build number of the database to the version its already upgraded. If we do not execute the query and start the server then server will start from 4.2.3 schema only. So by executing this we have saved sometime.

4. During the migration process there may be chances of elevated usage of JVM so make sure that the Perm Size, Heap size are defined properly to avoid any performance issues.

5. Also, If experiencing same problem during migration again and again at the same stage then do check the associated source files, Liferay has some issues in their upgrade process. You may end up coding in ext for making upgrade process proper.

6. Upgrade process never makes any changes to custom tables present within the Database, but if these tables are being used in conjunction with another out of box tables then there will be changes involved at each level.

7. Apart from all the above criteria there will still be issues which may come up during the migration. All such issues will be different from case to case.