Liquibase Command Line

Liquibase can be run from the command line by running:

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

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/releasing database changelog locks.

Any values found after the command on the command line invocation will be considered a command parameter. The command line processor will validate whether the command line parameters are allowed for the current command. If the current command does not allow command line parameters or the parameter appears to be an incorrect format, then an error message of ‘unexpected command parameter’ will be logged and the execution will terminate.

The command line migrator also allows you to

If you run the command line migrator without any arguments, you will get a help message listing these available commands:

Database Update Commands

CommandDescription
updateUpdates database to current version.
updateCount <value>Applies the next <value> change sets.
updateSQLWrites SQL to update database to current version to STDOUT.
updateCountSQL <value>Writes SQL to apply the next <value> change sets to STDOUT.
updateTestingRollbackUpdates the database, then rolls back changes before updating again.

Database Rollback Commands

CommandDescription
rollback <tag>Rolls back the database to the state it was in when the tag was applied.
rollbackToDate <date/time>Rolls back the database to the state it was in at the given date/time.
rollbackCount <value>Rolls back the last <value> change sets.
rollbackSQL <tag>Writes SQL to roll back the database to the state it was in when the tag was applied to STDOUT.
rollbackToDateSQL <date/time>Writes SQL to roll back the database to the state it was in at the given date/time version to STDOUT.
rollbackCountSQL <value>Writes SQL to roll back the last <value> change sets to STDOUT.
rollbackOneChangeSetRolls back a single changeset without needing to roll back other already applied changesets. Liquibase Pro Feature
rollbackOneChangeSetSQLWrites SQL to roll back a single changest to STDOUT. Liquibase Pro Feature
futureRollbackSQLWrites SQL to roll back the database to the current state after the changes in the changeslog have been applied.
updateTestingRollbackUpdates the database, then rolls back changes before updating again.

Diff Commands

CommandDescription
generateChangeLogGenerate a changelog from a database when adding Liquibase to a new project. Conceptually, does a diff of the current database to an empty database, creating a changelog that has all the changes needed to update an empty database.
diff [diff parameters]Writes description of differences between two databases to standard out.
diffChangeLog [diff parameters]Adds any differences between the databases specified to a changelog. Can append in any of the supported changelog formats.

Documentation Commands

CommandDescription
dbDoc <outputDirectory>Generates Javadoc-like documentation based on current database and change log.

Maintenance Commands

CommandDescription
changelogSyncMark all changes as executed in the database.
changelogSyncSQLWrites SQL to mark all changes as executed in the database to STDOUT.
clearCheckSumsRemoves current checksums from database. On next update changesets that have already been deployed will have their checksums recomputed, and changesets that have not been deployed will be deployed.
dropAllDrops all database objects owned by the user. DANGEROUS!
listLocksLists who currently has locks on the database changelog.
markNextChangeSetRanMark the next change set as executed in the database.
releaseLocksReleases all locks on the database changelog.
statusOutputs count (list if --verbose) of unrun change sets.
snapshotGathers the current database schema and displays that information to STDOUT. With options, can save the schema in JSON format, and that JSON snapshot can serve as a comparison database.
tag <tag>"Tags" the current database state for future rollback.
tagExists <tag>Checks whether the given tag already exists.
validateChecks the changelog for errors.

Required Parameters for most commands

OptionDescription
--changeLogFile=<path and filename>The changelog file to use.
--username=<value>Database username.
--password=<value>Database password.
--url=<value>Database JDBC URL.
--driver=<jdbc.driver.ClassName>Database driver class name.

Optional Parameters

OptionDescription
--classpath=<value>Classpath containing migration files and JDBC Driver. List multiple items using the standard path separator for your platform, which is a colon (:) on Mac/Linux, and a semicolon (;) on Windows.
--contexts=<value>ChangeSet contexts to execute.
--defaultSchemaName=<schema>Specifies the default schema to use for managed database objects and for Liquibase control tables.
--databaseClass=<custom.DatabaseImpl>Specifies a custom Database implementation to use
--defaultsFile=</path/to/file>File containing default option values. (default: ./liquibase.properties)
--includeSystemClasspath=<true or false>Include the system classpath in the Liquibase classpath. (default: true)
--promptForNonLocalDatabase=<true or false>Prompt if non-localhost databases. (default: false)
--currentDateTimeFunction=<value>Overrides current date time function used in SQL. Useful for unsupported databases.
--labels=<value>Filter the changelog using labels.
--logLevel=<level>Execution log level (debug, info, warning, severe, off).
--logFile=<filename>Rather than logging to console, send logging messages to a file.
--liquibaseProLicenseKey=<licenKey>A Liquibase Pro license key (base64 encoded string) unlocks additional features.
--helpOutput command line parameter help.
--dataOutputDirectoryDirectory where insert statement csv files will be kept (required by generateChangeLog command).
--propertyProviderClass=<properties.ClassName>custom Properties implementation to use

Required Diff Parameters

OptionDescription
--referenceUsername=<value>Base Database username.
--referencePassword=<value>Base Database password.
--referenceUrl=<value>Base Database URL.

Optional Diff Parameters

OptionDescription
--referenceDriver=<jdbc.driver.ClassName>Base Database driver class name.
--referenceDefaultSchemaName=<schema>Base Database default schema name.

Change Log Properties

OptionDescription
-D<property.name>=<property.value>Pass a name/value pair for substitution of ${} blocks in the change log(s).

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. If you have specified an option in a properties file and specify the same option on the command line, the value on the command line will override the properties file value.

Examples

Standard Update Run

java -jar liquibase.jar \
      --driver=oracle.jdbc.OracleDriver \
      --classpath=\path\to\classes:jdbcdriver.jar \
      --changeLogFile=com/example/db.changelog.xml \
      --url="jdbc:oracle:thin:@localhost:1521:oracle" \
      --username=scott \
      --password=tiger \
      update

Run update pulling changelogs from a .WAR file

java -jar liquibase.jar \
      --driver=oracle.jdbc.OracleDriver \
      --classpath=website.war \
      --changeLogFile=com/example/db.changelog.xml \
      --url=jdbc:oracle:thin:@localhost:1521:oracle \
      --username=scott \
      --password=tiger \
      update

Run update pulling changelogs from an .EAR file

java -jar liquibase.jar \
      --driver=oracle.jdbc.OracleDriver \
      --classpath=application.ear \
      --changeLogFile=com/example/db.changelog.xml \
      --url=jdbc:oracle:thin:@localhost:1521:oracle \
      --username=scott \
      --password=tiger \
      update

Don’t execute changesets, save SQL to /tmp/script.sql

java -jar liquibase.jar \
        --driver=oracle.jdbc.OracleDriver \
        --classpath=jdbcdriver.jar \
        --url=jdbc:oracle:thin:@localhost:1521:oracle \
        --username=scott \
        --password=tiger \
        updateSQL > /tmp/script.sql

List locks on the database change log lock table

java -jar liquibase.jar \
        --driver=oracle.jdbc.OracleDriver \
        --classpath=jdbcdriver.jar \
        --url=jdbc:oracle:thin:@localhost:1521:oracle \
        --username=scott \
        --password=tiger \
        listLocks

Runs Liquibase using defaults from ./liquibase.properties

java -jar liquibase.jar update

liquibase.properties

driver: oracle.jdbc.OracleDriver
classpath: jdbcdriver.jar
url: jdbc:oracle:thin:@localhost:1521:oracle
username: scott
password: tiger

Export Data from Database

This will export the data from the targeted database and put it in a folder “data” in a file name specified with <insert file name>.

java -jar liquibase.jar --changeLogFile="./data/<insert file name> " --diffTypes="data" generateChangeLog

Update passing changelog parameters

liquibase.bat update -Dengine=myisam

Unicode

MySQL

Add url parameters useUnicode=true and characterEncoding=UTF-8 to set character encoding to utf8.

Since v5.1.3 Connector/J now auto-detects servers 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

more information about MySQL Connector J Using Character Sets and Unicode