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.
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 as of Liquibase version 4.1, or you can set them as Java system properties 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 Creating and configuring 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
changeLogLockPollRate 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 --changeLogFile=newChangeLog.xml update
The syntax on Windows requires the
set JAVA_OPTS=-Dliquibase.changeLogLockPollRate=5 && liquibase --changeLogFile=newChangeLog.xml update
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.
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 Liquibase System Requirements specify a system with 1 GB of RAM. However, using Liquibase commands like
update 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 Liquibase’s generateChangeLog 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="-DXmx1g" liquibase --changeLogFile=newChangeLog.xml generateChangeLog
The syntax on Windows is:
set JAVA_OPTS=-DXmx1g && liquibase --changeLogFile=newChangeLog.xml generateChangeLog
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 --changeLogFile=path/to/changeLog.sql --url=jdbc:oracle:thin:@<tns alias name>?TNS_ADMIN=/path/to/oracle_files --classpath=path/to/ojdbc8.jar update
For more information about this example, see Connecting to an Oracle Database with Liquibase via Kerberos and Active Directory.
Note: The commands shown above only apply to the current shell. If you need to pass an environment variable to a child process without affecting the parent process, you can use the
export command on Mac/Linux or the
setx command on Windows.