Phil Factor

3 October 2024

• Flyway
• CLI basics

Installing and Upgrading the Flyway CLI

The Flyway command-line tool is self-contained, has no GUI and doesn’t rely on any external dependencies. It is straightforward to install on a range of platforms, adaptable to different infrastructures and easy to integrate into automated CI/CD pipelines. Once installed, Flyway requires minimal maintenance, especially when using automated tools like Docker or a Package Manager.

The ‘standard’ installation process simply involves installing Flyway on every machine where it’s required, then updating to later Flyway versions as required. However, with a bit of scripted automation we can make this process a lot simpler. Alternatively, for automated deployment pipelines, we can simply run Flyway from a Docker container.

Getting the latest version of Flyway

The Installers page of the documentation contains links to all the latest Redgate-maintained versions of the Flyway. If you are installing on a development machine, you can choose the package that includes the Flyway Desktop GUI, which then automatically installs the CLI itself. However, this article focuses on either manually installing the Flyway CLI, or using Flyway Docker.

Redgate offers three editions of Flyway—Community, Teams, and Enterprise—within a single code base. The Community edition is free, and you access the additional functionality in the Teams and Enterprise editions by acquiring per-user licenses. You can also download the open-source edition, though it may lag behind the Redgate-maintained Community edition and the OSS edition doesn’t support newer features like Flyway Pipelines. Flyway Community also offers a smoother upgrade path to the fully supported Teams and Enterprise editions.

Running Flyway from Docker

If you prefer to use Docker containers instead of maintaining an installation on each of your workstations, Flyway provides Docker images. This is also the simplest way to use Flyway in a CI/CD pipeline. Redgate maintains the official repository for Flyway CLI Docker images, providing detailed instructions for using the images, and covering topics such as adding configuration files. There is also a GitHub site for the Flyway Open Source Docker images.

Standard, manual install and upgrade

The manual install of the Flyway CLI will work for any edition of Flyway and is similar on any operating system. There is one download package for each platform (Windows, Linux, macOS). I’ll demo a manual install or upgrade on Windows, and then Linux.

The common principle is that you install Flyway into a standard directory in your system area, with each new version of the CLI installed into a fresh subdirectory, named after the Flyway CLI version. Flyway components are versioned, so if you just unzip a new version of Flyway over an existing one, rather than install it in a new subdirectory, this does not “replace” the files, it simply adds the new files and this can lead to complex errors, depending on which version of the libraries Java finds first. It is much safer to put each version in its own subdirectory. This also makes it easier both to maintain an installation at the latest version and switch back to an older version if necessary. For housekeeping, you can occasionally clear out any old subdirectories that you no longer need.

Installing on Windows

To install Flyway CLI on a Windows PC, simply create a Flyway directory in a suitable place within your system area. I use C:\Program Files\flyway.commandline\tools but you could equally install it alongside other Redgate tools in C:\Program Files\Red Gate\Flyway.

Then, just download the ZIP file and extract it into the Flyway directory you’ve created. This works because the zipped contents include a subdirectory named flyway-<version>, with the files within it. Alternatively, you can manually create a subdirectory, named after the Flyway version number and extract the files into it. Either way, you should end up with a Flyway install directory, and subdirectories, with the following composition:

At this stage, the most important subdirectory for most people would be the conf subdirectory because any Flyway configuration settings that are there will apply for all users. You might wish to update this .conf file with your own default settings. If so then when you install a new version, you can simply copy the Flyway configuration file across to the new conf directory.

The final step of the installation is to add the path of the new flyway-<version> subdirectory to the system’s Path environment variable. This allows you to run the Flyway command from any location. Since it’s unusual to be required to manually add or alter a path, I thought I ought to add instructions (it’s done for you automatically if you’re using the CLI installed via Flyway Desktop):

• Open the Start menu, start typing in Environment variables and click the Edit the system environment variables button.
• In the System Properties window click on the Environment Variables… button.
• In the new Environment Variables window, go to the System Variables panel, find and select the Path variable, then click Edit.
  • If this is your first installation of Flyway, click New and add the path to the Flyway directory containing the release you installed (for example, C:\program files\flyway.commandline\tools\Flyway-10.17.0).
  • If you’ve installed a newer version, make the new version current by editing the existing path to point to the latest version. Similarly, to revert, alter path back to the older version.

In the same Environment Variables window, I also add a couple of entries to the User variables for <user> panel. One is called FlywayInstallation and points to the location where I’ve placed the flyway.commandline directory, which helps with the automation of aliases (see later). The other is called FlywayProject and specifies the path to root directory from which I run Flyway projects.

Installing on Linux

The overall process is the same on Linux as for Windows, i.e., download the latest distribution, extract it into a flyway-<version> directory then set the Path environment variable (and any user variables you need). The following a manual install method is universal for any Linux distribution such as Ubuntu, Debian, CentOS, Fedora.

First, download the latest version of Flyway as a .tar.gz file from the Flyway downloads page or use wget to download the file directly:

wget https://download.red-gate.com/maven/release/com/redgate/flyway/flyway-commandline/<version>/flyway-commandline-<version>-linux-x64.tar.gz

Once downloaded, extract the .tar.gz file using Bash:

tar -xzf flyway-commandline-<version>-linux-x64.tar.gz

Once extracted, you can move the flyway-<version> directory to a system-wide location like /opt or /usr/local (alternatively you can create a symbolic link to wherever you downloaded Flyway, as shown on the download page):

sudo mv flyway-<version> /opt/flyway

To make Flyway easily accessible from anywhere, add it to your system’s Path variable. To do this, open your ~/.bashrc configuration file (or ~/.zshrc for Zsh shells) and add the following line:

>export PATH=$PATH:/opt/flyway/flyway-10.18.2

Then, reload the shell so that the path values are updated:

>source ~/.bashrc

To finish, you verify the installation by checking if Flyway is running the version you’ve just installed:

flyway -v

This should display the version number of Flyway, indicating that the installation was successful.

Simplifying the Flyway CLI upgrade

What I like about the described system of installing Flyway is that you get to keep old versions that you know and like so you can then “roll back” to the older version if necessary. You can then use scripting to make it easier to upgrade or downgrade Flyway versions. For example, you can use aliases in PowerShell (or Bash) to specify the version of Flyway that you want to use.

I use the following PowerShell routine that creates a PowerShell alias called Flyway.  To upgrade to the latest version just install it as described above and then run the routine. It will:

1. Check for the Flyway installation directory ($FlywayInstallation).
2. Find the latest installed Flyway version by scanning the Flyway directories.
3. Set or update the alias to point to the latest version’s flyway.cmd file.

Since the alias directs PowerShell to use the correct version, there is no need to adjust the Path environment variable. This also allows you to switch quickly between Flyway versions; you change the version of Flyway simply by changing the alias. For example, you might want to roll back to a previous version, if you need to compare behavior, or if there is a compatibility issue with your scripts.

Installing the Flyway CLI using a Package Manager (Chocolatey)

A manual install is straightforward, but it involves downloading the Flyway package from the network, and unzipping it, for each new version, for each machine. I have enough Windows machines that keeping them all up-to-date manually quickly becomes tiresome.

If you’re using the Flyway open-source edition, then you can greatly simply the install and upgrade process by using a Package Manager. I’ll demo Chocolatey but there are plenty of others that will serve (such as Ansible, Homebrew, Scoop, Puppet, Chef or APT).

The Flyway distribution for Package Managers like Chocolatey is not done by Flyway but left to volunteers. Updates have sometimes been sporadic, but for Chocolatey at least the job is now entirely automated and seems fine. Also, as noted, this only for Flyway open-source edition. If you want to use the Redgate editions, but don’t want to do manual installs on every machine, it’s much easier to go the Flyway Docker route.

To use Chocolatey, the command is …

choco install flyway.commandline  /y

and then double-check that you have a working version:

flyway -v

The great advantage of Chocolatey is that it upgrades, where possible, everything that it ever installs so you can just log into a machine, run PowerShell in administrator mode and it will make everything, including Flyway, up-to-date. It also deals with amending the path command.

Choco upgrade all -y

I find I can flit between versions perfectly happily in Flyway using an alias, even if the version was installed by Chocolatey.

The only general disadvantage I’ve found is that, even though you may be installing the same file on several machines within the network, any of these package managers will download the same file for each machine being installed rather than use the one downloaded file. It also might not provide the same level of control over the installation path and configuration as the manual method does.

Conclusion

If you are used to installing GUI tools, then Flyway Command-line will come as a nice surprise. It comes with all the JDBC connectors for its full range of supported RDBMSs, from the complex (e.g. Oracle/ SQL Server) to the simple (e.g. SQLite). This comes as a blessing when you need to keep a lot of installations of Flyway automatically up to date on a network. You can, to be sure, work the same trick using containers, but a simple installation and upgrade makes Flyway a very versatile tool for a whole range in size and style of CI and deployment requirements.