Submit Feedback

Upgrading Data Schemas

When you upgrade Liferay, you might run into incompatibility issues with your custom modules’ data schemas. There are three ways you can resolve these issues:

You can run upgrade processes with the database upgrade tool. Upgrade processes perform changes to your modules to ensure they’re compatible with the Liferay installation’s current data schema. They are useful in production environments where you already have stored data that you can’t risk losing or corrupting.
You can also set upgrade processes to run automatically when the portal starts and when modules are deployed. This is useful in development to when you must ensure all modules are up to date.
You can test schema changes quickly using the build auto-upgrade tool. The build auto-upgrade tool doesn’t actually perform upgrades to the data schema. It removes and recreates the tables and may cause data loss if used in a production environment.

Warning

Liferay does not support upgrade.database.auto.run and schema.module.build.auto.upgrade in production as enabling these properties can result in data loss or improper data upgrades. In production environments, leave the property in portal-developer.properties set tofalse. To update data schemas properly, use upgrade processes.

Upgrade Processes

After you release a custom application to production, Liferay might release an update that changes the data schemas. This can cause incompatibility issues if not addressed properly. You can change the data structure used by your module to adjust to the new, upgraded database. For instructions on creating upgrade processes, see Using Upgrade Processes.

Note

For instructions on creating upgrade processes in Liferay DXP 7.4 U9/Portal 7.4 GA13 and below, see Using Upgrade Processes in Earlier Versions.

Running Upgrade Processes Automatically

Create a portal-ext.properties file in your app server’s [Liferay_Home]/ folder if it doesn’t already exist.
Enable automatic upgrade processes by setting upgrade.database.auto.run to true in the properties file (you can skip this step if you’re using Developer Mode):
```
upgrade.database.auto.run=true;
```

Setting the global property upgrade.database.auto.run to true runs all upgrade processes at module activation. This is useful when working with other developers who might make changes to the schema.

By default, upgrade.database.auto.run is set to false. Normally, upgrade processes are run using the database upgrade tool.

Testing Schemas Changes

Create a portal-ext.properties file in your app server’s [Liferay_Home] folder if it doesn’t already exist.
Enable automatic upgrade processes by setting upgrade.database.auto.run to true in the properties file (you can skip this step if you’re using Developer Mode):
```
schema.module.build.auto.upgrade = true;
```

Setting the global property schema.module.build.auto.upgrade to true applies module schema changes for redeployed modules whose service build numbers have incremented. The build.number property in the module’s service.properties file indicates the service build number. Build auto-upgrade executes schema changes without massaging existing data. It leaves data empty for created columns, drops data from deleted and renamed columns, and orphans data from deleted and renamed tables. It updates databases quickly and automatically, but it is for development purposes only.

By default, schema.module.build.auto.upgrade is set to false. On any module’s first deployment, the module’s tables are generated regardless of the schema.module.build.auto.upgrade value.

The table below summarizes build auto-upgrade’s handling of schema changes:

Schema Change	Result
Add column	Create a new empty column.
Rename column	Drop the existing column and delete all its data. Create a new empty column.
Delete column	Drop the existing column and delete all its data.
Create or rename a table in Liferay’s built-in data source.	Orphan the existing table and all its data. Create the new table.