JAVA_OPTS Environment Variable

JAVA_OPTS is an environment variable that you can set to pass custom settings to the Java Virtual Machine (JVM) that runs Liquibase.

Uses

Some common use cases for the JAVA_OPTS environment variable are as follows:

Setting Liquibase properties

You can include all Liquibase properties in the Liquibase properties file, or you can set them as Java system properties by using the JAVA_OPTS variable. If you are using an earlier version of Liquibase, you must set them using JAVA_OPTS. For a list of available Liquibase properties, see Create and Configure a liquibase.properties File.

You can set one property at a time, or set multiple properties separated by a whitespace character. For example, to set the changelog-lock-poll-rate property when using the update command, open the command line and pass arguments to JAVA_OPTS using the -Dproperty=value format. On Mac/Linux machine, the syntax is as follows:

JAVA_OPTS="-Dliquibase.changeLogLockPollRate=5" liquibase update --changelog-file=newChangeLog.xml

The syntax on Windows requires the set command:

set JAVA_OPTS=-Dliquibase.changeLogLockPollRate=5 && liquibase update --changelog-file=newChangeLog.xml

Note: In Liquibase version 4.4.0 and above, the syntax for command options has been altered, so changeLogFile is now changelog-file. The old format is backwards compatible with 4.4.0, but the new format will not work in older versions of Liquibase.

Setting Liquibase configuration properties with JAVA_OPTS

In Liquibase 4.25.0+, you can pass the following Liquibase configuration properties in the JAVA_OPTS environment variable. In versions before 4.25.0, you can only set these configuration properties as environment variables in your operating system:

System environment variable Property in 4.25.0+ Definition
LIQUIBASE_HOME liquibase.home

The directory that points to the Liquibase installation location.
LIQUIBASE_LAUNCHER_DEBUG liquibase.launcher.debug

Enables the Liquibase debug mode, which produces more log output and allows the user to debug their database.
LIQUIBASE_LAUNCHER_PARENT_CLASSLOADER liquibase.launcher.parent_classloader

The classloader that runs Liquibase via either system or thread. This variable defaults to system.

You can set other Liquibase properties with JAVA_OPTS in any version of Liquibase.

Memory allocation

You can use the JAVA_OPTS variable to allocate memory for Liquibase commands in the JVM. By default, the amount of memory available to the JVM is based on your total system memory. The specify a system with 1 GB of RAM. However, using Liquibase commands like diff on large databases may require additional memory.

For example, to set the maximum size of the memory heap that the JVM can access while executing the Liquibase generate-changelog command, you can use the -Xmx<value><unit> option as part of the value of the JAVA_OPTS variable. On a Mac/Linux machine, the syntax is as follows:

JAVA_OPTS="-Xmx1g" liquibase generate-changelog --changelog-file=newChangeLog.xml

The syntax on Windows is:

set JAVA_OPTS=-Xmx1g && liquibase generate-changelog --changelog-file=newChangeLog.xml

Database connection

Another use case for the JAVA_OPTS variable is to establish a secure database connection using Liquibase, such as with the Kerberos authentication protocol. An example command that you can use with an Oracle database on a Mac/Linux machine is as follows:

JAVA_OPTS=-Djava.security.krb5.conf=/path/to/krb5.conf
-Doracle.net.kerberos5_cc_name=/path/to/kerbcache
-Dsun.security.krb5.debug=true
-Doracle.net.kerberos5_mutual_authentication=true
-Doracle.net.authentication_services=KERBEROS5 liquibase update
--changelog-file=path/to/changeLog.sql
--url=jdbc:oracle:thin:@<tns alias name>?TNS_ADMIN=/path/to/oracle_files
--classpath=path/to/ojdbc8.jar

For more information about this example, see Connecting to an Oracle Database with Liquibase via Kerberos and Active Directory.

Note: These commands only apply to the current shell. To set permanent environment variables, see Liquibase Environment Variables.

Related links