Liquibase Launch Script

Liquibase comes with a launch script called liquibase (liquibase.bat on Windows) at the top level of the Liquibase installation folder. This script configures Java to run the Liquibase launcher through your command line interface (CLI).

When run, the liquibase launch script does the following:

  1. Chooses the correct version of Java:
    1. If you already set the JAVA_HOME environment variable, the launch script uses the Java version there
    2. Otherwise, if you installed the CLI via an installer, the launch script uses the Java version bundled with the version of Liquibase you installed
    3. Otherwise, the launch script uses the Java version configured in the PATH environment variable
  2. Includes any additional Java arguments set in the JAVA_OPTS Environment Variable

Warning: This batch script is the default and recommended way to run Liquibase via CLI. Please do not customize this launch script. Any changes you make will be untested by Liquibase and could result in unexpected launch script behavior.

Passing JAVA_OPTS and classpath

The default Liquibase launch script can include Java system properties set in the JAVA_OPTS Environment Variable.

Here is an example of setting JAVA_OPTS prior to invoking the liquibase launch script with status command:

JAVA_OPTS="-Doracle.net.tns_admin=/opt/oracle/instantclient_12_1/network/admin -Djava.security.krb5.conf=/etc/krb5.conf -Doracle.net.kerberos5_cc_name=/etc/krb5cc -Dsun.security.krb5.debug=true -Doracle.net.kerberos5_mutual_authentication=true -Doracle.net.authentication_services=KERBEROS5 -Djava.security.auth.login.config=/etc/JDBCDriverLogin.conf"

echo "JAVA_OPTS="$JAVA_OPTS" liquibase status --verbose"

/opt/liquibase/liquibase status --verbose

By default, the liquibase launch script includes the system classpath when resolving classes at runtime. You can modify this behavior with the --include-system-classpath argument.

Run Liquibase without the launcher

Liquibase recommends that users launch Liquibase using the default launch script provided in each release. However, if you need to run Liquibase directly from Java, you can use the java -jar command to directly run commands and automatically build a classpath:

  1. Set the LIQUIBASE_HOME environment variable to a directory containing a lib and an internal/lib directory, which contain the JAR files to add to the classpath
  2. In your command line, run this command:
    3. java -jar LIQUIBASE_HOME/internal/lib/liquibase-core.jar <liquibase arguments>

Note: <liquibase arguments> does not contain a call to the liquibase BAT file. For example, update --changelog-file=foobar.xml instead of liquibase update --changelog-file=foobar.xml.

Best practices

Liquibase may alter the default launch script in future releases. Modifying the default launch script is highly discouraged. It is a best practice to use the default launch script. This avoids potential issues that may arise from changes to the Liquibase codebase.

While changes impacting how Liquibase is launched are uncommon and are always documented in Liquibase Release Notes, using the default launch script can prevent the need for changes to existing pipelines when these types of changes are made to Liquibase.

Related links