Command Line Interface

The command line migrator works well when you want to do migrations on demand, but don't have Ant or Maven available such as on servers. The command line migrator also gives you more control over the process than the Servlet Listener, Ant, or Maven do, allowing you to run maintenance commands like outputting SQL and listing or releasing database changelog locks.

You can run all Liquibase commands using the CLI. Although there are significant backend changes in how you can configure Liquibase or how you can type commands in Liquibase 4.4, the Liquibase CLI functionality aims to be backward compatible with all previous versions. However, it is a best practice to follow the syntax rules mentioned in this instruction and in the --help output.

Argument Locations

There are two types of flags or arguments you can specify—global arguments and command arguments:

  • The global arguments are not a part of the command and are not specific to a command. They represent a way to change the overall default behavior. Examples of global arguments include logLevel, catalogName, and others.
  • The command arguments are the settings for a particular command. Some command arguments are required, some of them are optional. Examples of command settings include changelogFile, password, username, referenceUrl, and others.

Use global arguments before the command name and command arguments after the command name.

liquibase [global options] [command] [command parameters]

Liquibase parses any other arguments as command arguments. However, it does not support the positional argument style. Positional arguments are unnamed arguments that come after the command. For example: git pull origin. Using Liquibase style, you would specify it as follows: git pull --remote=origin.

Global and Command Arguments Syntax

Global and command arguments have namespaces associated with them to avoid conflicts between extensions. To prevent extensions from conflicting with Liquibase settings, Liquibase uses the liquibase namespace in the defaults files: liquibase.logLevel. When specifying arguments in the CLI, you can drop the --liquibase- part. For example: --logLevel.

Argument Keys and Values

To assign values to arguments, use the equal sign (=) between them.

Example: --url=jdbc:h2:/mem

Alternatively, you can use a space to assign a value to an argument.

Example: --url jdbc:h2:/mem

Multi-Word Arguments

Some arguments consists of multiple words, such as the reference URL and reference username. Follow the syntax rules below when using word arguments, even if you see examples of them as a camelCased word:

  • Separate words using a dash (-)
  • Use lowercase letters: --reference-url
  • Do not use two dashes or space in the middle of the global or command argument.

Configuration Hierarchy for CLI Arguments

Liquibase supports setting properties in multiple locations, with the final value determined in the chart in which the top locations take precedence over lower locations:

Command line arguments Override ServletConfig and ServletContext init parameters, Java system properties, OS environment variables, and configuration data
ServletConfig init parameters Override ServletContext init parameters, Java system properties, OS environment variables, and configuration data
ServletContext init parameters Override Java system properties, OS environment variables, and configuration data
Java system properties Override OS environment variables and configuration data
OS environment variables Override configuration data
Configuration data, such as liquibase.properties file, piped standard input, or defaults files Does not override any values

Using a liquibase.properties file

If you do not want to always specify options on the command line, you can create a properties file that contains default values. By default, Liquibase will look for a file called liquibase.properties in the current working directory, but you can specify an alternate location with the --defaultsFile flag. For more information, see Creating and configuring a liquibase.properties file.

Related Links