Migrating Liferay Instances

Liferay DXP 2025.Q2+

Beta Feature

You can migrate virtual instances across different Liferay installations by exporting and importing 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.

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

On releases before 2025.Q3, these operations use the earlier extract and insert names. The schema prefix is lextracted_, the configuration keys are extractCompanyId and insertCompanyId, and the configuration files are named ExtractPortalInstanceConfiguration.config and InsertPortalInstanceConfiguration.config. The System Settings entries carry the matching earlier names.

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.

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 export with these parameters for the source database:

   • --company-id [arg]: Company ID of the virtual instance to export.
   • --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 uses the schema in the --jdbc-url parameter.
   • --user [arg]: Name of the database user.
   • --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 validate with these 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.

Exporting a Database Partition

After ensuring the databases are compatible, you can export a partition from the current installation by creating a new database schema. You can import this schema into a different installation or use it independently as a single-instance installation. After the export, the virtual instance remains fully functional in the source database.

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

2. Go to Platform → Virtual Instances → Instance Export.

3. In the Export Company ID field, enter the company ID of the virtual instance to export.

Alternatively, you can export the partition using OSGi configurations:

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

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

   exportCompanyId=L"12345"
   

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

This process creates a new database schema called lexported_[companyId], which you can import into the target Liferay installation. The export deletes the configuration file to avoid repeating the process.

Importing 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 → Instance Import.

3. Fill the Import 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 import the partition using OSGi configurations:

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

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

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

   • importCompanyId: 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 imported.

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

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

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 lexported_[companyId] schema from the standalone partition into lpartition_[companyId]. Then, the import deletes the configuration file to avoid repeating the process.

Copying a Database Partition

You can also copy virtual instances within a Liferay installation.

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

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

3. In the Name field, enter a name for the virtual instance copy.

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. Optionally, fill the Destination Company ID field with an ID for the copy. If you leave it blank, Liferay assigns a unique one. The source virtual instance is unchanged either way.

8. Click Save.

9. Check that the copy 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. Check that the copy is available and functioning as expected.