Command-line
Published 16 November 2022
Command-line
The Flyway command-line tool is a standalone Flyway distribution. It runs on Windows, macOS and Linux and it is primarily meant for users who wish to migrate their database from the command-line without having to integrate Flyway into their applications nor having to install a build tool.
Flyway Pipelines
Flyway Pipelines can be used in conjunction with the Flyway CLI to give you a centralized view of deployment status, history and health metrics for every database deployment you and your team make.
Access Flyway Pipelines at Welcome to Flyway (red-gate.com).
Download and installation
Windows
flyway-commandline-11.0.1-windows-x64.zip
Extract the archive and simply add the new flyway-11.0.1
directory to the PATH
to make the flyway
command available from anywhere on your system.
macOS
flyway-commandline-11.0.1-macosx-x64.tar.gz
Linux
Download, extract and install by adding to PATH
(requires sudo
permissions):
$ wget -qO- https://download.red-gate.com/maven/release/com/redgate/flyway/flyway-commandline/11.0.1/flyway-commandline-11.0.1-linux-x64.tar.gz | tar -xvz && sudo ln -s `pwd`/flyway-11.0.1/flyway /usr/local/bin
Or simply download the archive:
flyway-commandline-11.0.1-linux-x64.tar.gz
Docker
(Linux only) Download, extract and install by adding to PATH
(requires sudo
permissions):
$ sudo sh -c 'echo "docker run --rm redgate/flyway:11.0.1 $*" > /usr/local/bin/flyway && chmod +x /usr/local/bin/flyway'
(All platforms) Or simply download the image:
> docker pull redgate/flyway:11.0.1
Go to Docker Hub for detailed usage instructions.
Directory structure
The Flyway download, once extracted, now becomes a directory with the following structure:
flyway
conf/ Configuration file(s)
drivers/ JDBC Drivers
jre/
lib/
licenses/
sql/ SQL migrations
flyway macOS/Linux executable
flyway.cmd Windows executable
Usage
> flyway [options] command
Command Line flags
The following flags provide helpful information without carrying out any other operations:
Flag | Purpose |
---|---|
--help -h -? |
Print the list of available commands and options |
--version -v |
Print the Flyway version |
The following flags modify the console output
Flag | Purpose |
---|---|
-X |
Extended debug output enabled |
-q |
Quiet mode,suppress all output, except for errors and warnings |
-color | Colorize the terminal output |
-outputType | Human or machine-readable output |
Commands
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 |
Undo | Undoes the most recently applied versioned migrations |
Baseline | Baselines an existing database, excluding all migrations up to and including baselineVersion |
Repair | Repairs the schema history table |
Auth | Licenses flyway usage |
JDBC drivers
In order to connect with your database, Flyway needs the appropriate JDBC driver to be available in its drivers
directory.
To see if Flyway 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 Flyway 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 Flyway Command-line tool can be configured in a wide variety of ways.
You can find out more in the Configuration section of the documents
Command-line Arguments
Finally, Flyway can also be configured by passing parameters directly from the command-line:
flyway -user=myuser -schemas=schema1,schema2 -placeholders.keyABC=valueXYZ migrate
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:
> flyway info -url="jdbc:snowflake://ab12345.snowflakecomputing.com/?db=demo_db&user=foo"
Powershell: use double-quotes inside single-quotes:
> ./flyway info -url='"jdbc:snowflake://ab12345.snowflakecomputing.com/?db=demo_db&user=foo"'
Commandline Namespacing
Flyway commandline arguments follow the same namespacing as the configuration files, with the flyway
part assumed.
For example, the flyway.url
configuration parameter can be set on the commandline as flyway -url=jdbc://xxx
.
To avoid conflicts, many plugins and extensions use a different namespace, such as flyway.init
or flyway.diff
.
When configuring these, there are two options;
Option 1: Use the full namespace on the commandline:
flyway init -init.databaseType=sqlserver
Option 2: Use scoped namespacing:
When the namespace is the same as the verb, you can configure parameters for that verb directly following that verb and have the namespace assumed;
flyway init -databaseType=sqlserver
this will be interpreted as flyway.init.databaseType=sqlserver
. When using scoped namespacing, you must have the
parameters follow the verb and proceeding other verbs.
This will fail, as the info
verb is not expecting the databaseType
parameter:
flyway init info -databaseType=sqlserver
to allow for this to work, you have to ensure a logical order; for the above, either of the following would work;
flyway info init -databaseType=sqlserver
flyway init -databaseType=sqlserver info
In both cases, the databaseType
comes after the init
verb and before any other verb,
so it is assumed to be `flyway.init.databaseType=sqlserver
Backwards Compatibility:
Scoped namespacing is automatically disabled when ANY namespace is used. This is to maintain backwards compatibility with scripts written for older versions of Flyway. To clarify, the following two examples will work;
flyway init -databaseType=sqlserver -projectName=myProject
flyway init -init.databaseType=sqlserver -init.projectName=myProject
but the following will not;
flyway init -init.databaseType=sqlserver -projectName=myProject
because the databaseType
parameter is namespaced, scoped namespacing is disabled and thus projectName
is assumed to be
flyway.projectName
and not flyway.init.projectName
.
Configuration from standard input
See Configuration from Standard Input
Overriding order
See CLI Configuration Order for details of the configuration mechanism priority.
Credentials
If you do not supply a database user
or password
via any of the means above, you may be
prompted to enter them (depending on the database):
Database user: myuser Database password:
If you want Flyway 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 pass custom arguments to Flyway's JVM, you can do so by setting the JAVA_ARGS
environment variable, either at runtime or persistently on the host system.
They will then automatically be taken into account when launching Flyway. This is particularly useful when needing to set JVM system properties.
Runtime example (Windows cmd)
> set JAVA_ARGS=-Xms308M -Xmx432M
The corresponding system environment variable would be Name: JAVA_ARGS Value: -Xms308M -Xmx432M
See Oracle's documentation for a full list of available JAVA_ARGS.
Output
By default, all debug, info and warning output is sent to stdout
. All errors are sent to stderr
.
Flyway 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 Flyway's automatic detection is to put all the necessary JAR files in Flyway's lib
folder and any configuration in the Flyway root folder.
For example, if you wished to use log4j
v2 with the Flyway command line, you would achieve this by placing the log4j JAR files and the corresponding configuration file log4j2.xml
like this:
flyway-11.0.1 conf drivers jre lib log4j-api-2.17.1.jar log4j v2 jar log4j-core-2.17.1.jar log4j v2 jar licenses sql log4j2.xml log4j configuration
Similarly, to use Logback
add the relevant files like this:
flyway-11.0.1 conf drivers jre lib logback-classic.1.1.7.jar Logback jar logback-core-1.1.7.jar Logback jar slf4j-api-1.7.21.jar Logback dependency licenses sql logback.xml Logback configuration
If you are building Flyway into a larger application, this means you do not need to explicitly wire up any logging as it will automatically detect one of these frameworks.
P6Spy
P6Spy is another approach to logging which operates at the driver or datasource level, and Flyway has integration with this. You can read about setting it up here and configuring it here.
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
> flyway migrate -X | grep -v 'term-to-filter-out'
Powershell
> flyway migrate -X | sls -Pattern 'term-to-filter-out' -NoMatch
Windows cmd
> flyway migrate -X | findstr /v /c:"term-to-filter-out"
Writing to a file
Add -outputFile=/my/output.txt
to the argument list to also write output to the specified file.
Open Source Flyway
This project is a core part of Flyway and you can find more information about it in Flyway Open Source