Flyway can be used as a command line with no configuration outside the Flyway install if desired.

However, for any use of Flyway which is going to be version controlled it is helpful to have a standard structure and configuration pattern.

Projects are defined by a flyway configuration file; the default name is flyway.toml. There can in principle be any number of toml configuration files, the settings of which will be merged together in the order in which they are defined, but a recommended standard practice would be to store all settings which should be shared with your team in flyway.toml and store that in Version Control and store settings which are specific to your local machine in a flyway.user.toml file and exclude that from Version Control.

A complete list of project settings, documented according to the hierarchy in the settings file, can be found here.

For more guidance on creating Flyway projects, see Creating a new project.

For more guidance on getting up and running against an existing project, see Setting up an existing project from version control.

Default folder structure

New projects created using flyway init or Flyway Desktop add the following folders and files to the project by default:

The contents of these files and folders will vary depending on database type.

Note that the schema model folder is only added for databases for which Flyway has Database Comparison engine support.

User settings

All project settings can be overridden in the user settings file, flyway.user.toml.

It is recommended that the user settings file be ignored by git, so that local user settings are not shared, and this is configured by default when initializing a project through flyway.

By default, the Flyway Desktop development and shadow  database connection information is stored in the user settings file instead of the project file as it is likely to vary between users. It can be stored in the project settings directly if desired (e.g., if everyone on the team has the same development database or everyone uses localhost).

Default project file locations

By default, Flyway will load TOML files from the following locations in the order given below:

• {installDir}/conf/flyway.toml
• {installDir}/conf/flyway.user.toml
• {userhome}/flyway.toml
• {userhome}/flyway.user.toml
• {executionDir}/flyway.toml
• {executionDir}/flyway.user.toml
• {workingDirectory}/flyway.toml
• {workingDirectory}/flyway.user.toml

When invoking Flyway from the CLI, configuration files can instead be specified using the configFiles parameter.

.conf settings (legacy)

The TOML format was designed as a replacement for the older .conf format of Flyway configuration files.

The .conf format is in most respects a Java ".properties" file, representing a series of key value pairs. While in many respects visually similar to the .conf format the .toml format is much richer.

.conf files can be upgraded to the new format using Flyway Desktop or the command line

flyway-dev.json settings (deprecated)

Older Flyway Desktop projects will include flyway-dev.json, flyway-dev.user.json, and flyway.conf in place of the toml configuration files.

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.

Reasons to upgrade from .conf to .toml

1. The biggest improvement over 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.
2. 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 environment option. It is no longer necessary to use multiple flyway.conf files or rely on specifying the url when using the command line.
   
3. It is also possible for these environments to contain values with deferred resolution using the new resolvers concept or for these environments to be spun up on demand using provisioners.
4. 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.
5. Future options and features may be added to the toml format but not backported to the older configuration formats.

Configuration precedence

If a parameter is defined in multiple TOML files then the value from the last loaded TOML file will take precedence and overwrite any previously defined value. Once all TOML files have been loaded, parameters will be read from environment variables and command line arguments in that order, and can overwrite any previously defined value.

Flyway does not support the simultaneous use of both Legacy CONF format and TOML format in the same environment.

For a complete run down of how Flyway loads configuration, see Configuration Precedence.