When Flyway's check verb was released in Flyway V9 we needed a way of specifying a temporary database to use to build the result of your migrations (see check concept). This led to some new parameters in Flyway:

• check.buildUrl

• check.buildUser

• check.buildPassword

In Flyway V10 we introduced the ability to specify environments which is a much richer way of expressing how Flyway should connect to your database.

• As an example, there is no schemas parameter for the legacy V9 parameters which can lead to Flyway using the database default schema for it's build which may not be what you intended.

This post covers some of the ways you could update your pipeline to take advantage of what environments can offer - either through command line or configuration file updates.

How to update your CLI commands

If you are using Flyway in a pipeline and specifying things from the command line then you've got some choices.

How it works today

When you have an existing command line like this:

flyway -url="jdbc:postgresql://localhost/production" -user="postgres" -password="****" -schemas="sales" -check.buildUrl="jdbc:postgresql://localhost/checkdb" -check.buildUser="postgres" -check.buildPassword="****" check -drift

Behind the scenes, params like -url, -password, -schemas... all get mapped into an environment called default so you see things like this in the logs:

environments.default.password -> ********
environments.default.schemas -> [sales]
environments.default.url -> jdbc:postgresql://localhost/production
environments.default.user -> postgres

-check.buildURL/buildPassword/buildUser is a lot less rich than a Flyway environment and it has no way of specifying other options - It's one of the reasons why we are deprecating these in favor of environments.

You'll have seen warnings like this in the log output:

- WARNING: check.buildUrl is deprecated and will be removed in a future release. Please use check.buildEnvironment instead.

How to update your CLI

In order to update, we need to specify an environment with the parameters we require and then tell check to use that.

If we replace the following parts of the command:

-check.buildUrl="jdbc:postgresql://localhost/checkdb" -check.buildUser="postgres" -check.buildPassword="****"

with this (we're defining an environment called "build"):

-environments.build.url="jdbc:postgresql://localhost/checkdb" -environments.build.user="postgres" -environments.build.password="****"

.. and add the check.buildEnvironment to tell Flyway which environment to use for the build using this:

-check.buildEnvironment="build"

Then we have made the change. Putting it all together looks like this:

flyway -url="jdbc:postgresql://localhost/production" -user="postgres" -password="****" -schemas="sales" -environments.build.url="jdbc:postgresql://localhost/checkdb" -environments.build.user="postgres" -environments.build.password="****" -check.buildEnvironment="build" check -drift

and of course you can now specify schemas for your build environment by adding 

-environments.build.schemas="sales"

Using the TOML file

TOML is Flyway's new configuration file format (don't worry, it's quite similar to the old conf format).

You can easily specify your environments in there to simplify the command line and the integration with your Flyway Desktop project that saves your project in a compatible TOML format.

It has the advantage that multiple environments can be specified in a single file (previously this would have required a lot of .conf file juggling) and you can specify any of the environment parameters in here.

For example, here we will specify two environments, prod and build in our flyway.toml file:


[environments.prod]

url= "jdbc:postgresql://localhost/production"

user= "postgres" password="****"

schemas= ["sales"]

[environments.build]

url= "jdbc:postgresql://localhost/checkdb"

user= "postgres" password="****"

schemas= ["sales"]

[flyway]

environment = "prod"

[flyway.check]

buildEnvironment = "build"

Calling flyway can be as simple as:

flyway check -drift

(We've used the Flyway environment parameter to allow us to define an environment called prod to replace the naked url/password/user/... that we used earlier.)

...and yes, you wouldn't put secrets into a configuration file so you can use one of the Flyway property resolvers to pull in items from environment variables or secrets managers.