Submit Feedback

Data Cleanup

Before database upgrades, Liferay executes data cleanup processes to repair databases with obsolete data. This lightens the load of the upgrade tool, improving performance and reducing overhead.

As of Liferay DXP 2025.Q3/Portal 2026, these processes are run automatically before every upgrade. In earlier versions, Liferay already provided a simple way to run them manually.

Automatic Pre-Upgrade Data Cleanup

Liferay DXP 2025.Q4+/Portal 2026.Q1+

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

You can also execute data cleanup processes manually on a running Liferay instance:

  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.