Command-line tool

The MigrateDB command-line tool is a standalone MigrateDB distribution. It is primarily meant for users who wish to migrate their database from the command-line without having to integrate MigrateDB into their applications nor having to install a build tool.

Download and installation

Download from GitHub.

Directory structure

The MigrateDB download, once extracted, now becomes a directory with the following structure:

📂 migratedb-1.0.0
  📂 conf
    📄 migratedb.conf    configuration file
 📁 drivers              JDBC drivers
 📁 jars                 Java-based migrations (as jars)
 📁 lib
 📁 licenses
 📁 sql                  SQL migrations
 📄 migratedb            macOS/Linux executable
 📄 migratedb.cmd        Windows executable

Usage

migratedb [options] command

Help flags

The following flags provide helpful information without carrying out any other operations:

`--help` `-h` `-?`	Print the list of available commands and options
`--version` `-v`	Print the MigrateDB version

Commands

The following commands are available:

Name	Description
migrate	Migrates the database
clean	Drops all objects in the configured schemas
info	Prints the details and status information about all the migrations
validate	Validates the applied migrations against the ones available on the classpath
baseline	Baselines an existing database, excluding all migrations up to and including baselineVersion
repair	Repairs the schema history table

JDBC drivers

In order to connect with your database, MigrateDB needs the appropriate JDBC driver to be available in its drivers directory.

To see if MigrateDB ships with the JDBC driver for your database, visit the Driver section of the documentation page for your database. For example, here is the Oracle Drivers section.

If MigrateDB does not ship with the JDBC driver, you will need to download the driver and place it in the drivers directory yourself. Instructions on where to download drivers from are also in the Driver section of the documentation page for each database, under Maven Central coordinates.

Configuration

The MigrateDB Command-line tool can be configured in a wide variety of ways. You can use config files, environment variables and command-line parameters. These different means of configuration can be combined at will.

Config files

Config files are supported by the MigrateDB command-line tool. If you are not familiar with them, check out the MigrateDB config file structure and settings reference first.

MigrateDB will search for and automatically load the following config files if present:

<install-dir>/conf/migratedb.conf
<user-home>/migratedb.conf
<current-dir>/migratedb.conf

It is also possible to point MigrateDB at one or more additional config files. This is achieved by supplying the command line parameter -configFiles= as follows:

migratedb -configFiles=path/to/myAlternativeConfig.conf migrate

To pass in multiple files, separate their names with commas:

migratedb -configFiles=path/to/myAlternativeConfig.conf,other.conf migrate

Relative paths are relative to the current working directory. The special option -configFiles=- reads from standard input.

Alternatively you can also use the MIGRATEDB_CONFIG_FILES environment variable for this. When set it will take preference over the command-line parameter.

export MIGRATEDB_CONFIG_FILES=path/to/myAlternativeConfig.conf,other.conf
migratedb migrate

By default, MigrateDB loads configuration files using UTF-8. To use an alternative encoding, use the command line parameter -configFileEncoding= as follows:

migratedb -configFileEncoding=ISO-8859-1 migrate

Alternatively you can also use the MIGRATEDB_CONFIG_FILE_ENCODING environment variable for this. When set it will take preference over the command-line parameter.

export MIGRATEDB_CONFIG_FILE_ENCODING=ISO-8859-1

Environment Variables

To make it easier to work with cloud and containerized environments, MigrateDB also supports configuration via environment variables. Check out the MigrateDB environment variable reference for details.

Command-line Arguments

Finally, MigrateDB can also be configured by passing arguments directly from the command-line:

migratedb -user=myuser -schemas=schema1,schema2 -placeholders.keyABC=valueXYZ migrate

A note on escaping command-line arguments

Some command-line arguments will need care as specific characters may be interpreted differently depending on the shell you are working in. The url parameter is particularly affected when it contains extra parameters with equals = and ampersands &. For example:

bash, macOS terminal and Windows cmd: use double-quotes:

migratedb info -url="jdbc:snowflake://ab12345.snowflakecomputing.com/?db=demo_db&user=foo"

Powershell: use double-quotes inside single-quotes:

./migratedb info -url='"jdbc:snowflake://ab12345.snowflakecomputing.com/?db=demo_db&user=foo"'

Configuration from standard input

You can provide configuration options to the standard input of the MigrateDB command line, using the ` -configFiles=-` option. MigrateDB will expect such configuration to be in the same format as a configuration file.

This allows you to compose MigrateDB with other operations. For instance, you can decrypt a config file containing login credentials and pipe it straight into MigrateDB.

Examples

Read a single option from echo:

echo $'migratedb.url=jdbc:h2:mem:mydb' | migratedb info -configFiles=-

Read multiple options from echo, delimited by newlines:

echo $'migratedb.url=jdbc:h2:mem:mydb\nmigratedb.user=sa' | migratedb info -configFiles=-

Use cat to read a config file and pipe it directly into MigrateDB:

cat migratedb.conf | migratedb migrate -configFiles=-

Use gpg to encrypt a config file, then pipe it into MigrateDB.

Encrypt the config file:

gpg -e -r "Your Name" migratedb.conf

Decrypt the file and pipe it to MigrateDB:

gpg -d -q migratedb.conf.gpg | migratedb info -configFiles=-

Overriding order

The MigrateDB command-line tool has been carefully designed to load and override configuration in a sensible order.

Settings are loaded in the following order (higher items in the list take precedence over lower ones):

Command-line arguments
Environment variables
Standard input
Custom config files
<current-dir>/migratedb.conf
<user-home>/migratedb.conf
<install-dir>/conf/migratedb.conf
MigrateDB command-line defaults

The means that if for example migratedb.url is both present in a config file and passed as -url= from the command-line, the command-line argument will take precedence and be used.

Credentials

If you do not supply a database user or password via any of the means above, you will be prompted to enter them:

Database user: myuser
Database password:

If you want MigrateDB to connect to your database without a user or password, you can suppress prompting by adding the -n flag.

There are exceptions, where the credentials are passed in the JDBC URL or where a password-less method of authentication is being used.

Java Arguments

If you need to to pass custom arguments to MigrateDB’s JVM, you can do so by setting the JAVA_ARGS environment variable. They will then automatically be taken into account when launching MigrateDB. This is particularly useful when needing to set JVM system properties.

Output

By default, all debug, info and warning output is sent to stdout. All errors are sent to stderr.

MigrateDB will automatically detect and use any logger class that it finds on its classpath that derives from any of the following:

the Apache Commons Logging framework org.apache.commons.logging.Log (including Log4j v1)
SLF4J org.slf4j.Logger
Log4J v2 org.apache.logging.log4j.Logger

Alternatively, you can use the loggers configuration parameter to specify an exact desired logging framework to use.

The simplest way to make use of MigrateDB’s auto-detection is to put all the necessary JAR files in MigrateDB’s lib folder and any configuration in the MigrateDB root folder. For example, if you wished to use Logback with the MigrateDB command line, you would achieve this by placing the Logback JAR files and the corresponding configuration file logback.xml like this:

  📂 migratedb-1.0.0
  📁 conf
  📁 drivers
  📁 jars
  📂 lib
    📄 logback-classic.1.2.3.jar         Logback jar
    📄 logback-core-1.2.3.jar            Logback jar
    📄 slf4j-api-1.7.30.jar              API jar
  📁 licenses
  📁 sql
  📄 logback.xml                         Logback configuration

If you are building MigrateDB into a larger application, this means you do not need to explicitly wire up any logging as it will auto-detect one of these frameworks.

P6Spy

P6Spy is another approach to logging which operates at the driver or datasource level, and MigrateDB has integration with this. You can read about setting it up here and configuring it here.

Colors

By default, the output is automatically colorized if stdout is associated with a terminal.

You can override this behavior with the -color option. Possible values:

auto (default) : Colorize output, unless stdout is not associated with a terminal
always : Always colorize output
never : Never colorize output

Debug output

Add -X to the argument list to also print debug output. If this gives you too much information, you can filter it with normal command-line tools, for example:

bash, macOS terminal

migratedb migrate -X | grep -v 'term-to-filter-out'

Powershell

migratedb migrate -X | sls -Pattern 'term-to-filter-out' -NoMatch

Windows cmd

migratedb migrate -X | findstr /v /c:"term-to-filter-out"

Quiet mode

Add -q to the argument list to suppress all output, except for errors and warnings.

Machine-readable output

Add -outputType=json to the argument list to print JSON instead of human-readable output. Errors are included in the JSON payload instead of being sent to stderr.

Writing to a file

Add -outputFile=/my/output.txt to the argument list to also write output to the specified file.

Command-line: migrate ➡️