Liferay's Database Upgrade Tool Gets Earlier Validation and Smarter Defaults

This is LR Tools’ rewrite of a post by István Dézsi on Liferay.dev covering a set of fixes to Liferay’s database upgrade tool, driven by a review of common support tickets and customer frustration with the old setup.

The old problem: failures that showed up too late

The database upgrade tool’s setup used to be unforgiving in a specific way: a single wrong path in a properties file, or picking a database edition your license doesn’t actually support, and you could be several minutes into a run before hitting a cryptic error with no real hint about what went wrong. DXP 2026.Q1 addresses that directly, with changes aimed at one goal: catch mistakes before you commit to a run, not partway through it.

Fewer surprises: validation moved earlier

The tool now detects whether the install is DXP or Community Edition and only offers databases that edition actually supports — instead of letting you pick an unsupported one and fail later with an opaque “Unsupported database type” error. As you type paths interactively (Liferay home, app server, libraries, portal directories), the tool checks they actually exist; it resolves the database host via DNS; and it validates the port falls in the 0–65535 range. Bad input now produces an immediate, specific message and re-prompts, instead of surfacing as a failure deep into the run.

If you configure manually via app-server.properties and portal-upgrade-ext.properties instead of the interactive wizard, those files now get validated up front too — the tool checks the server type is recognized, that referenced directories exist, and that there isn’t a stray portal-ext.properties sitting in the home directory that could conflict. A bad path used to surface as a confusing ClassNotFoundException; now it names the actual problem and stops cleanly.

Less to configure: smarter defaults and reuse

If no database is yet configured for the upgrade, the tool now reads your existing portal-ext.properties and offers to reuse its JDBC settings — driver class, URL, username, with the password masked — via a simple “Use existing JDBC properties (y/N)” prompt. Say yes and the database prompts are skipped entirely; anything you explicitly set for the upgrade still takes priority over the reused values.

Configuration itself is now consolidated into a single portal-upgrade-ext.properties file, matching how the rest of Liferay is configured. The old separate portal-upgrade-database.properties file is deprecated — if the tool finds one, it warns and ignores it rather than silently using stale settings.

JVM options get sensible defaults filled in automatically now too. Run the tool with:

./db_upgrade_client.sh -j "-Xmx8192m"

and your custom -Xmx8192m is kept while standard parameters you didn’t specify (-Dfile.encoding, -Duser.country, -Duser.language, -Duser.timezone) get filled in behind the scenes — anything you do set explicitly still wins. Default directory paths now use explicit relative notation (./bin, ./lib, ./webapps/ROOT) so uncommenting the defaults doesn’t trip a validator rule against absolute paths, and the default Tomcat directory is simply ./tomcat now, matching what current bundles and Docker images actually ship.

Better defaults, better performance

The default max heap size moves from 2048 MB to 4096 MB — the old default was a common cause of out-of-memory failures on larger databases, and it’s still overridable via --jvm-opts if you need more.

More usefully, the tool now automatically rewrites the JDBC connection URL to enable each database’s batch-insert optimization, something that used to be a manual step:

Existing URL parameters are preserved, and anything you’ve set manually is left alone. Because this rewrite happens at every connection-pool initialization — not just during upgrades — the same speed benefit carries over into normal portal startup too. The wizard’s suggested default database is also now PostgreSQL, reflecting what the tool’s maintainers say is the more common production choice today; every supported database remains selectable at the prompt.

The overall shift

None of these changes are individually dramatic, but together they change what the tool feels like to use: it surfaces problems before you commit to a run instead of after, reuses configuration you already have instead of asking you to retype it, and defaults to sensible settings instead of ones that quietly cause out-of-memory failures. Less time spent on setup and cryptic failures, more time on the actual upgrade.

This article is LR Tools’ rewrite of the original post by István Dézsi — read it on Liferay.dev for the author’s own framing.