If you have ever run a Liferay database upgrade, you know how unforgiving the setup used to be. One wrong path in a properties file, or a database your edition doesn't even support, and you could be several minutes into a run before a cryptic error appeared, usually with no hint about what actually went wrong. We went back through the most common support cases and customer frustrations, and shipped a round of improvements aimed squarely at them in Liferay DXP 2026.Q1. The upgrade tool now catches mistakes earlier, asks you for less, and runs faster out of the box.

Here's what changed.

Fewer Surprises

The biggest theme is simple: the tool now tells you something is wrong before the upgrade starts, not halfway through it.

It only offers databases you can actually use

The tool detects whether you're running DXP or Community Edition and lists only the databases that edition supports. Choosing an incompatible database used to fail late with an opaque "Unsupported database type." Now it simply isn't on the menu.

It validates your input as you type it

Directory paths (Liferay home, application server, libraries, portal) are checked for existence, the database host is checked for DNS resolution, and the port is checked against the valid 0-65535 range. When something doesn't add up, you get a clear message and the prompt repeats, instead of a failure deep into the run.

It validates your configuration files up front

If you prefer editing app-server.properties and portal-upgrade-ext.properties directly, the tool now verifies them before doing any work: the server type is one it recognizes, the directories exist, and there's no stray portal-ext.properties in your home directory waiting to cause a conflict. A bad path used to surface as a baffling ClassNotFoundException. Now you get a message that names the problem and stops cleanly so you can correct it.

Less to Configure

The second theme: the tool reuses what it can find, so you stop repeating yourself.

It reads your existing database settings

On first run, if you haven't configured a database for the upgrade, the tool reads portal-ext.properties from your Liferay home and offers to reuse those JDBC settings, with the password masked:

An existing database configuration was found in: /path/to/portal-ext.properties
	jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver
	jdbc.default.url=jdbc:mysql://localhost:3306/lportal
	jdbc.default.username=root
	jdbc.default.password=**********

Use existing JDBC properties (y/N):

Answer y and the database prompts are skipped entirely. Anything you set explicitly for the upgrade still takes precedence.

One configuration file instead of two

All upgrade settings now live in a single portal-upgrade-ext.properties, matching the way the rest of Liferay is configured. The old, separate portal-upgrade-database.properties is deprecated: if it's present, the tool warns you and ignores it.

Sensible JVM defaults are filled in for you

Passing custom options no longer means re-specifying the essentials. Run this:

./db_upgrade_client.sh -j "-Xmx8192m"

and the tool keeps your -Xmx8192m while filling in the parameters you left out (-Dfile.encoding, -Duser.country, -Duser.language, -Duser.timezone). Anything you set explicitly always wins.

Paths and the Tomcat directory match modern bundles

Default directory paths now use explicit relative notation (./bin, ./lib, ./webapps/ROOT), so uncommenting the defaults no longer trips the validator that forbids absolute paths. The default Tomcat directory is now simply ./tomcat, matching what recent bundles and Docker images ship.

Better Defaults and Performance

More memory by default

The default maximum heap is now 4096 MB, up from 2048 MB, which was too tight for larger databases and a frequent cause of out-of-memory failures. You can still override it with --jvm-opts.

Automatic batch-insert optimization

The tool now rewrites your JDBC URL to enable each vendor's batch-insert path automatically:

Existing parameters are preserved, and anything you've set yourself is left alone. This used to be a manual step you had to know about; now it's on by default. As a bonus, the rewriting runs on every connection-pool initialization, so the same speedup applies to normal portal startup, not just the upgrade.

PostgreSQL is the new default

The interactive wizard now suggests PostgreSQL, with its driver and connection defaults, reflecting how most production installs are configured today. Any supported database is still a keystroke away at the prompt.

Wrapping Up

None of these changes are dramatic on their own. Together, they shift the upgrade tool from something you have to fight with into something that meets you halfway: it tells you what's wrong before you commit to a run, reuses the configuration you already have, and picks sensible defaults so you don't have to. Less time spent on setup and cryptic errors means more time for the upgrade itself.

These improvements are tracked under epic LPD-59502.

— István