Submit Feedback
Preparing for an Upgrade

Data Cleanup

Liferay executes data cleanup processes to repair databases with obsolete data. This lightens the load during an upgrade, improving performance and reducing overhead.

As of Liferay DXP 2025.Q4, these processes are run automatically before and after every upgrade. In earlier versions, Liferay already provided a simple way to run them manually.

Automatic Pre-Upgrade Data Cleanup

Liferay DXP 2025.Q4+

Before every upgrade and after running the verify processes, the data cleanup processes check the database for the most frequent causes of upgrade failure. Then, they remove orphan data that is no longer needed, fix incorrect values, and erase references to data that no longer exists.

If a data cleanup process fails, the upgrade is stopped immediately and the error is logged in the console. The Upgrade Report contains additional information, mostly in the upgrade_report_diagnostics.txt file, under the Data clean up section.

The automatic data cleanup is enabled by default and can be disabled by setting the upgrade.database.preupgrade.data.cleanup.enabled portal property to false.

Note

If you’re upgrading with the Database Upgrade Tool, set the portal property in the tools/portal-tools-db-upgrade-client/portal-upgrade-ext.properties file.

Blacklisting Cleanup Processes

Even though the cleanup processes only affect obsolete data, you can choose to protect data you deem important by blacklisting the process that would repair it. Create a blacklist of cleanup processes by setting the upgrade.database.preupgrade.data.cleanup.blacklist property to the name of the DataCleanupPreupgradeProcess classes that should not be executed:

upgrade.database.preupgrade.data.cleanup.blacklist=\
	com.liferay.portal.upgrade.data.cleanup.AnalyticsMessageDataCleanupPreupgradeProcess,\
	com.liferay.portal.upgrade.data.cleanup.GroupDataCleanupPreupgradeProcess
Note

If you’re upgrading with the Database Upgrade Tool, set the portal property in the tools/portal-tools-db-upgrade-client/portal-upgrade-ext.properties file.

Manually Cleaning Up Data

Manual data cleanup processes appear as Cleanup Actions and affect either the entire system or individual modules. System cleanup actions target core system tables and data, while module cleanup actions target module tables and data. Module cleanup actions only appear if the module existed in the old version and is detected in the Liferay installation. The process differs depending on your Liferay version.

Liferay DXP 2026.Q1+

First, clean up the system data.

  1. Open the Global Menu and go to Control Panel → Server Administration → Resources →System Cleanup Actions.

    Clean up the system data first.

  2. Click Execute to remove the data.

Important

Only remove published change tracking store content data if you’re using a Liferay version before 7.3 U10 or 7.4 U37. After running the task, perform your upgrade to prevent further accumulation of this unnecessary data.

Next, remove obsolete data from old, unavailable apps and modules.

  1. Open the Global Menu and go to Control Panel → Server Administration → Resources → Module Cleanup Actions.

    Clean up the module data next.

  2. Click Execute to remove the outdated module data.

Note

The module cleanup action can only be executed once. Upon completion, the module’s release entry is removed and does not appear on subsequent system startups to avoid redundant cleanups.

Liferay DXP 7.4 to Liferay DXP 2025.Q4

  1. Open the Global Menu (Global Menu) and go to Control Panel → System Settings → Upgrades → Data Removal.

    Go to the Data Removal tab.

  2. Select the data to remove:

    • Expired Journal Articles

    • Document Library Preview Change Tracking Store Content Data (Publications)

    • Published Change Tracking Store Content Data (Publications)

    Important

    Only remove Published Change Tracking Store Content Data if you’re using a Liferay version before 7.3 U10 or 7.4 U37. After running the task, upgrade to prevent further accumulation of this unnecessary data.

  3. Click Save.

Liferay executes the data cleanup processes and removes obsolete data from your current available apps and modules. To remove all data from old, unavailable apps and modules,

  1. Open Global Menu (Global Menu) again and go to Control Panel → System Settings → Upgrades → Data Cleanup.

    Data Cleanup provides an interface for removing data from obsolete Liferay applications.

  2. Select the modules you want to clean up and click Save.

    Note

    To save the cleanup settings to a configuration file, click the Actions menu and select Export.

Your server is clear of obsolete data and Data Cleanup is disabled automatically for all the modules. This prevents unnecessary, redundant data cleanup.

Cleaning Up Data Before 7.4

In Liferay versions 7.3 and earlier, Data Cleanup settings persist. To disable cleanup in these older versions, uncheck every module in the Data Cleanup screen and click Save or set the module cleanup keys false in a com.liferay.data.cleanup.internal.configuration.DataCleanupConfiguration.config configuration file.

Note

You can also clean up module data on server startup (in a Liferay Docker container or on a local machine) using a com.liferay.data.cleanup.internal.configuration.DataCleanupConfiguration.config configuration file. After the cleanup, prevent subsequent server startups from running the cleanups again by removing the configuration file from the osgi/configs folder.