Migrating Liferay Instances

Liferay DXP 2025.Q2+/Portal GA148+

Beta Feature

You can migrate virtual instances across different Liferay installations by extracting and inserting database partitions. You might do this to move an existing virtual instance from Liferay Self-Hosted to Liferay PaaS, for example. You can also copy virtual instances in an installation.

Important

Currently, this feature is behind a beta feature flag (LPD-11342).

Note

A Liferay installation contains other infrastructure components that aren’t extracted in the standalone partition like the Document Library and Search indexes. These must be handled independently when migrating or copying virtual instances.

In the extraction step, Liferay creates a standalone partition with copies of tables from the current installation’s virtual instance database. This triggers a new database schema called lextracted_[companyId]. In the insertion step, the standalone partition in the current installation’s database is integrated as a new virtual instance.

Important

To export or insert a virtual instance in Liferay SaaS, contact Liferay Cloud Support.

Validating a Database Partition

Before you begin, you must ensure the databases are ready. Liferay contains a tool to validate database partitions before performing a migration. It analyzes the source and target databases and indicates whether they are compatible.

Important

Both the source and target environments must use MySQL or PostgreSQL and must be on the same Liferay version.

The Database Partition Migration Validator Tool operates in two modes: export and validation.

Export Mode

To run the tool in export mode,

1. Go to the bundles/tools/portal-tools-db-partition-migration-validator folder. There is a .jar file of the tool and a script to execute it.

2. Execute db_partition_migration-validator.sh with the following parameters for the source database:

   • --company-id [arg]: Company ID of the virtual instance to extract.
   • --jdbc-url [arg]: JDBC URL.
   • --output-dir [arg] (Optional): Directory where tool outputs generated JSON file. By default, files are generated in the exports folder.
   • --password [arg]: Password of the database user.
   • --schema-name [arg] (Optional): Database schema name of the source partition. By default, the tool extracts the schema in the --jdbc-url parameter.
   • --help (Optional): Display parameter information.

3. Execute the command again for the target database.

Export mode creates two JSON files containing information on the source and target databases. Validation mode uses these files to check if they are compatible.

Validation Mode

After generating both JSON files with export mode, you can use the same Database Partition Migration Validator Tool to validate them. To run the tool in validation mode,

1. Still in the bundles/tools/portal-tools-db-partition-migration-validator folder, execute db_partition_migration-validator.sh again with the following parameters:

   • --source-file [arg]: File with the information of the source partition generated by the tool in export mode.
   • --target-file [arg]: File with the information of the target partition generated by the tool in export mode.
   • --help (Optional): Display parameter information.

Extracting a Database Partition

After ensuring the databases are compatible, you can extract a partition from the current installation by creating a new database schema. This schema is able to be inserted into a different installation or even be used independently as a single instance installation. After the extraction, the virtual instance is still fully functional in the source database.

1. In the Global Menu (), navigate to Control Panel → Configuration → System Settings.

2. Go to Platform → Virtual Instances.

3. In the Extract Company ID field, enter the standalone partition’s company ID.

Alternatively, you can extract the partition using OSGi configurations:

1. Create a file named com.liferay.portal.instances.internal.configuration.ExtractPortalInstanceConfiguration.config.

2. Write the company ID in the .config file. For example,

   extractCompanyId=L"12345"
   

3. Deploy the configuration file by moving it to [Liferay Home]/osgi/configs.

This process creates a new database called lextracted_[companyId] which can be imported in the target Liferay installation to perform the insertion process. The extraction deletes the configuration file to avoid repeating the process.

Inserting a Database Partition

Lastly, you can integrate the standalone partition into another installation.

1. In the Global Menu (), navigate to Control Panel → Configuration → System Settings.

2. Go to Platform → Virtual Instances → Portal Instance Insertion.

3. Fill the Insert Company ID field with the company ID of the standalone partition. The ID must be different from any in the target installation.

4. Optionally, fill the New Name, New Virtual Hostname, and New Web ID fields to change these properties in the new installation.

5. Start the new server and check that the migrated instance is available and functioning as expected.

Alternatively, you can insert the partition using OSGi configurations:

1. Create a file named com.liferay.portal.instances.internal.configuration.InsertPortalInstanceConfiguration.config.

2. Write the following fields into the .config file:

   insertCompanyId=L"12345"
   newName="aNewName"
   newVirtualHostname="aNewVirtualHostName"
   newWebId="aNewWebId"
   

   • insertCompanyId: The virtual instance ID of the standalone partition. The ID must be different from any in the target installation.

   • newName (Optional): Changes the company name for the virtual instance when it is inserted.

   • newVirtualHostname (Optional): Changes the virtual hostname for the virtual instance when it is inserted.

   • newWebId (Optional): Changes the web ID for the virtual instance when it is inserted.

3. Deploy the configuration file by moving it to [Liferay Home]/osgi/configs.

4. Start the new server and check that the migrated instance is available and functioning as expected.

This process renames the lextracted_[companyId] database from the standalone partition into lpartition_[companyId]. Then, the insertion deletes the configuration file to avoid repeating the process.

Copying a Database Partition

You can also copy virtual instances within a Liferay installation.

Important

This feature is only available for MySQL and PostgreSQL.

1. In the Global Menu (), navigate to Control Panel → Configuration → System Settings.

2. Go to Platform → Virtual Instances → Portal Instance Copy.

3. In the Name field, enter the standalone partition’s company ID. The ID must be different from any in the target installation.

4. In the Source Company ID field, enter the company ID of the virtual instance to be copied.

5. Fill the Virtual Hostname field with a new virtual hostname for the virtual instance copy.

6. Fill the Web ID field with a new web ID for the virtual instance copy.

7. If you wish to keep the old virtual instance, fill the Destination Company ID field with a new ID for the copy. Leaving this field blank overrides the old virtual instance with the new one.

8. Click Save.

9. If you didn’t choose a new ID for the copy, delete the old virtual instance and restart the server to check that the instance is available and functioning as expected.

Alternatively, you can copy the virtual instance using OSGi configurations:

1. Create a file named com.liferay.portal.instances.internal.configuration.CopyPortalInstanceConfiguration.config.

2. Write the following fields into the .config file:

   sourceCompanyId=L"12345"
   name="www.able.com"
   virtualHostname="www.able.com"
   webId="www.able.com"
   

   • sourceCompanyId: The ID of the virtual instance to be copied.

   • destinationCompanyId (Optional): The new ID for the virtual instance copy.

   • name: The new name for the virtual instance copy.

   • virtualHostname: The new virtual hostname for the virtual instance copy.

   • webId: The new web ID for the virtual instance copy.

3. Deploy the configuration file by moving it to [Liferay Home]/osgi/configs.

4. If you didn’t choose a new ID for the copy, delete the old virtual instance and restart the server to check that the instance is available and functioning as expected.