Working with Command Parameters
To run Liquibase commands by using the CLI, follow the syntax rules in this topic and the --help
output. For a list of parameters, see Liquibase Parameters.
Locations
Command parameters are specified as either of the following types:
- Global parameters provide a way to change an overall default behavior. Specified before the command, global parameters are neither part of nor specific to a particular command. Examples include
--log-level
and--catalog-name
. - Command parameters specify command settings and are sometimes required for a particular command. Examples of command settings include
--changelog-file
,--password
,--username
, and--reference-url
. Specify command parameters after the command.
The following example shows the appropriate positioning of global and command parameters with respect to the command.
liquibase <global parameters> <command> <command parameters>
Note: Liquibase version 4.4 turned some global parameters into command parameters. Pre-4.4 syntax is supported in 4.4+ versions.
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
.
Tip: 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:
- Command-line arguments
ServletConfig
initialization parametersServletContext
initialization parameters- Java system properties
- OS environment variables
- 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.
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.
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.
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
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.