Working with command parameters

Locations

Liquibase parameters are one of two types:

• Global parameters change an overall default behavior. They are not specific to any single command, and you can use them with every command. Examples include --log-level and --catalog-name.

• Command parameters specify settings for a particular command, and some commands require them. Examples include --changelog-file, --password, --username, and --reference-url.

You can place any parameter anywhere on the command line, before or after the command name. Both of the following examples are valid:

liquibase --log-level=INFO update --changelog-file=example-changelog.xml liquibase update --changelog-file=example-changelog.xml --log-level=INFO

Note: In Liquibase Secure 5.2.1 and earlier, global parameters must be placed before the command name and command parameters after it.

Syntax

To avoid conflicts between extensions, namespaces are associated with global and command parameters. For Liquibase settings, Liquibase uses the liquibase namespace in the defaults file, for example liquibase.logLevel.

When using the CLI to specify paramters, drop the liquibase. portion, for example --log-level.

For best results, specify all commands and parameters in the --kebab-case format in the CLI. If your preference is camelCase, it also works in the CLI.

Parameter keys and values

Use the equal sign (=) to assign values to parameters.

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

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

Example: --url jdbc:h2:/mem

Multi-word parameters

Some parameters consists of multiple words, such as the reference URL and reference username. When constructing multi-word parameters, use the following syntax guidelines, even if examples present them as camelCased variants:

• Use a dash (-) to separate words

• Use lowercase letters, like --reference-url

• Do not insert spaces or multiple dashes in a global or command parameter

Configuration hierarchy

Liquibase supports the setting of properties from the following locations, from highest to lowest priority:

1. Liquibase flow file stage parameters

2. Liquibase flow file global parameters

3. Command-line arguments

4. ServletConfig initialization parameters

5. ServletContext initialization parameters

6. Java system properties

7. OS environment variables

8. Configuration data, such as piped standard input, defaults files, and connection profiles and other properties stored in the Liquibase properties file.

For example, command-line arguments override ServletConfig and ServletContext initialization parameters, Java system properties, OS environment variables, and configuration data, while OS environment variables override configuration data only.

Liquibase properties file

To avoid specifying options repeatedly on the command line, create a Liquibase properties file that contains default values. By default, Liquibase searches the current working directory for a file named liquibase.properties, but you can specify an alternate location with the --defaults-file parameter.

For more information, see Create and Configure a liquibase.properties File.

Liquibase command line migrator

To perform migrations on demand without Ant or Maven, use the Liquibase command-line migrator, which allows you to run maintenance commands for outputting SQL and listing or releasing database changelog locks. The migrator provides more control than even the Servlet Listener.

Examples

Standard update run

liquibase \ --search-path=path/to/changelog/files \ update \ --changelog-file=com/example/db.changelog.xml \ --url="jdbc:oracle:thin:@localhost:1521:oracle" \ --username=scott \ --password=tiger

Run update pulling changelogs from a .WAR file

liquibase \ --seach-path=website.war \ update \ --changelog-file=com/example/db.changelog.xml \ --url=jdbc:oracle:thin:@localhost:1521:oracle \ --username=scott \ --password=tiger

Run update pulling changelogs from an .EAR file

liquibase \ --search-path=application.ear \ update \ --changelog-file=com/example/db.changelog.xml \ --url=jdbc:oracle:thin:@localhost:1521:oracle \ --username=scott \ --password=tiger

Do not run changesets, save SQL to /tmp/script.sql

liquibase \ --search-path=path/to/changelog/files \ update-sql > /tmp/script.sql \ --url=jdbc:oracle:thin:@localhost:1521:oracle \ --username=scott \ --password=tiger

List lock records in the DATABASECHANGELOGLOCK table

liquibase \ list-locks \ --url=jdbc:oracle:thin:@localhost:1521:oracle \ --username=scott \ --password=tiger

Run Liquibase using defaults from the Properties file

liquibase update

Example Properties

searchPath: path/to/changelog/files url: jdbc:oracle:thin:@localhost:1521:oracle username: scott password: tiger

Export data from a database

The following example exports data from the target database to a file named <insert file name> in a folder named data:

liquibase generate-changelog --diff-types="data" --changelog-file="./data/<insert file name>"

Update passing changelog parameters

liquibase.bat update -Dengine=myisam

MySQL Unicode

Note: Modifying the{encoding|fileEncoding} setting causes checksum mismatches for previously applied changesets. If your changeset edits are safe and intentional, you can explicitly tell Liquibase to accept the new checksum using validCheckSum. See How to resolve checksum errors for more information.

To set character encoding to utf8, add the URL parameters useUnicode=true and characterEncoding=UTF-8.

Note: Connector/J v5.1.3 and later either detects servers that are configured with character_set_server=utf8mb4 or treats the Java encoding utf-8 passed using characterEncoding=… as utf8mb4.

--url="jdbc:mysql://localhost/dbname?useUnicode=true&characterEncoding=UTF-8"

For more information, visit MySQL Connector J Using Character Sets and Unicode.