Project settings
Published 11 October 2021
The new unified toml format
Flyway projects created by Flyway Desktop generate a flyway.toml file, which contains all settings used across Flyway Desktop and the Flyway command lines.
The full spec of the settings file can be found here and many of the settings can be configured through the Flyway Desktop UI.
Reasons to upgrade from the json and conf formats
- The biggest improvement over these previous formats is that the toml format contains all the settings for both Flyway Desktop and the Flyway command line in a single file so settings no longer need to be duplicated.
- Another major feature is that the toml file allows the configuration of multiple database environments which can easily be referenced from the Flyway command line using the new
environmentoption. It is no longer necessary to use multiple flyway.conf files or rely on specifying the url when using the command line. - It is also possible for these environments to contain values with deferred resolution using the new resolvers concept. We will be expanding on this with more documented options soon.
- The toml format is easier to update manually than json and is richer and easier to organize than conf, so it should provide a better experience.
- Future options and features may be added to the toml format but not backported to the older configuration formats.
Things to be aware of when upgrading
Upgrading your Flyway project will require all users of this project to be using Flyway Desktop 6.5.0 or greater and Flyway Engine 9.20.1 or greater. This may involve updating the version used in your continuous integration or continuous deployment pipelines.
Deployment pipelines ought to otherwise continue working unchanged. One exception to this is if the .conf configuration files are explicitly referenced using the configFiles command line property. In this case, these references need to be updated to reference the toml file.
How to upgrade from the old json format
The easiest way to upgrade a json Flyway project (flyway-dev.json) is to open that project in Flyway Desktop and click the Upgrade project button which will show up at the top.
How to upgrade from using flyway.conf
The easiest way to upgrade a flyway conf file to the new toml format is to open Flyway Desktop and click on the Import button.
