Upgrade Stall Detection
Liferay DXP 2026.Q3+
During a database upgrade, Liferay DXP checks the database every 60 seconds and logs queries that appear stalled. You can use these messages to tell whether a query is waiting for another database session to release a lock or is merely slow.
Stall detection only reports. It never ends or unblocks a session, and it runs only during an upgrade.
Stall detection works with every database Liferay DXP supports.
Configuring Upgrade Stall Detection
Stall detection is enabled by default, so no property is required to turn it on. Set these portal properties to tune the thresholds or to turn it off:
| Property | Default | Description |
|---|---|---|
upgrade.query.monitor.enabled | true | Stall detection runs during every upgrade. Set this property to false to turn it off. |
upgrade.query.monitor.lock.threshold | 300000 (five minutes) | A query waiting on a resource lock longer than this value in milliseconds is logged at the WARN level. |
upgrade.query.monitor.long.running.threshold | 600000 (10 minutes) | An active query running longer than this value in milliseconds, without waiting on a lock, is logged at the INFO level. |
The properties are read when the upgrade starts, so set them before you launch the upgrade. No property changes the 60-second check interval.
If you upgrade at startup, set the properties in the portal-ext.properties file in Liferay Home. For example, to report a lock wait after two minutes and a slow query after five, you can use these values:
upgrade.query.monitor.lock.threshold=120000
upgrade.query.monitor.long.running.threshold=300000
If you use the Database Upgrade Tool, set the same properties in your [Liferay Home]/tools/portal-tools-db-upgrade-client/portal-upgrade-ext.properties file.
The upgrade report lists overridden portal properties and the files they were set in, so you can use it to confirm your values took effect.
Reading the Log Messages
Each line names the query text, the database session ID, and the elapsed duration in seconds. Durations are reported in seconds, while the thresholds are configured in milliseconds.
| Level | Message |
|---|---|
WARN | Locked query "<query>" with ID <id> has been running for <N> seconds |
INFO | Long running query "<query>" with ID <id> has been running for <N> seconds |
When a query’s schema differs from Liferay DXP’s default catalog or schema, the message adds in schema "<schema>" after the ID.
Stall detection logs a line for every qualifying query on every check, so a query that stays locked is reported again every 60 seconds with a growing duration. These example lines show both conditions:
Locked query "alter table AssetEntry add priority DOUBLE" with ID 4718 has been running for 372 seconds
Long running query "update DLFileEntry set fileName = title" with ID 4802 in schema "lportal_archive" has been running for 655 seconds
A WARN lock line means another database session holds a lock the upgrade needs. The reported session ID is the upgrade’s own blocked session, not the session holding the lock. Give it to your database administrator to trace the blocker. An INFO long-running line means the query is still executing, so no intervention is required. To confirm that a slow query is advancing rather than stalled, enable upgrade progress logging.
Search the log for Long running to find the INFO lines. The message text has no hyphen, unlike the long.running property name. When you run the Database Upgrade Tool, the -l option sets the log file name.
The logged query text is truncated at 4000 characters, so a long statement can appear cut off. This limit isn’t configurable. On PostgreSQL the database truncates the text first, to one byte less than the track_activity_query_size setting (1024 bytes by default), so Liferay DXP’s own limit rarely applies there.
Long-running query messages appear only when INFO logging is enabled. Lock warnings are logged at WARN, so they appear even when the log level is less verbose than INFO.
When Stall Detection Stops or Reports Nothing
If stall detection can’t reach or query the database, Liferay DXP logs one WARN message and stall detection stops for the rest of the upgrade. The upgrade itself continues, without further stall reporting:
Upgrade query monitoring is disabled: <exception message>
The most likely cause is that the database user lacks permission to see other sessions’ activity. Databases don’t all report that the same way. On SQL Server the database returns no rows rather than raising an error, so stall detection keeps checking and reports nothing at all. What the log shows, and what your database administrator must grant, depend on the database:
| Database | What the log shows | Grant |
|---|---|---|
| DB2 | DB2 SQL Error: SQLCODE=-1092 | db2 update dbm cfg using SYSMON_GROUP <group>, then restart the instance |
| MariaDB and MySQL | Access denied; you need (at least one of) the PROCESS privilege(s) for this operation | GRANT PROCESS ON *.* TO '<user>'@'<host>'; |
| Oracle | Grant select privileges on "sys.v_$session" and "sys.v_$sql", or assign "SELECT_CATALOG_ROLE" or "DBA", because the database user lacks the required select privileges | GRANT SELECT ON sys.v_$session TO <user>; and GRANT SELECT ON sys.v_$sql TO <user>;, or GRANT SELECT_CATALOG_ROLE TO <user>; |
| PostgreSQL | No message | Not required |
| SQL Server | No message | USE master; GRANT VIEW SERVER STATE TO <login>; |
The full DB2 line also carries SQLSTATE, SQLERRMC (the authorization ID), and DRIVER, but SQLCODE=-1092 is the part that identifies the missing authority.
These grants are instance-wide or server-wide rather than scoped to the upgrade’s database, so the database user can read other sessions’ query text across the server. Stall detection runs only during an upgrade, so your database administrator can revoke the permission once the upgrade finishes. After granting it, run the upgrade again to get stall reporting.
On SQL Server, a database user without VIEW SERVER STATE sees no warning at all. Stall detection reports nothing for the whole upgrade, so a stalled upgrade looks the same as a healthy one. Grant the permission before you start if you want stall reporting.
If stall detection doesn’t shut down within five seconds of being stopped at the end of the upgrade, Liferay DXP logs this message. The upgrade isn’t affected:
Unable to terminate upgrade query monitor within 5 seconds