TOML Configuration File

How it works in Flyway

Loading

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

These can be changed by using the configFiles parameter.

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.

Root level Parameters

Root level parameters (e.g locations) inherit the namespace of the table and are read using just the parameter name.

Feature Verbs

When using feature verbs (e.g flyway.check), you can include that as a table header with the parameters underneath;

[flyway.check]
deployedSnapshot = "my_snapshot"

Or you can include the parameters under the flyway table, with the feature verb added before the parameter.

[flyway]
check.deployedSnapshot = "my_snapshot"

Root Namespaces

Flyway supports namespaces for flyway, environments and for other Redgate products.

[newNamespace]
value="my_value"

Environments

Environments are created using the environment table and hold parameters that are part of that specific deployment target.

Environment Specific Parameters

There are many parameters that are specific to an environment.

When creating an environment, you will need to set the flyway.environment parameter with the environment you wish to use.

[flyway]
environment="env1"

This is a list of all those parameters that are in [environments]. Other parameters are read from [flyway].

[environments.env1]
url = "jdbc:h2:mem:flyway_db"
user = "myuser"
password = "mysecretpassword"
driver = "org.h2.Driver"
schemas = ["schema1", "schema2"]
connectRetries = 10
connectRetriesInterval = 60
initSql = "ALTER SESSION SET NLS_LANGUAGE='ENGLISH';"
jdbcProperties = { accessToken = "access-token" }
resolvers = ["my.resolver.MigrationResolver1", "my.resolver.MigrationResolver2"]

Default Environment

The default environment is an initially loaded environment called default that is used if no other environment is specified. It can be configured by the user. Check the environments for their default values.

[environments.default]
user = "myuser"
password = "mysecretpassword"

Property Resolvers

Configuration values can be retrieved from other sources, such as Hashicorp Vault, Google Secrets or Dapr, using Property Resolvers.

Example of conf to TOML

flyway.conf

flyway.url=jdbc:h2:mem:flyway_db
flyway.user=myuser
flyway.password=mysecretpassword
flyway.locations=filesystem:sql
flyway.check.deployedSnapshot=my_snapshot

flyway.toml

[environments.env1]
url = "jdbc:h2:mem:fylway_db"
user = "myuser"
password = "mysecretpassword"

[flyway]
locations = ["filesystem:sql"]

[flyway.check]
deployedSnapshot = "my_snapshot"

FAQ

Why aren't my parameters in my environment picked up by Flyway?

You may need to specify the environment under [flyway] or from the commandline. For example with an environment called env1, in TOML, you would need to do the following:

[environments.env1]
...

[flyway]
environment="env1" 

In commandline, you would need to do the following:

./flyway -environment=env1 migrate

Why are the wrong parameters values being read?

You may have another toml config that is being read which is overwriting the TOML you expect to use.

The default file paths are:

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

Why are there other sections in the config?

The new configuration format allows separating configuration into domains (tables in TOML definition) and these are used to facilitate expansion and coordination in the Flyway suite.

Why am I getting "unknown configuration parameters" errors?

You may have a parameter under the wrong table. Check the namespace it is under and move it to the correct table. Environment specific parameters are listed here.

You may also be trying to configure a teams/enterprise config parameter in OSS edition. Check the parameters for the list of parameters that are not available in OSS edition.

Why am I getting "Unknown escape sequence" errors?

Values in double quotes allow for escape sequences initiated with a \ as per the TOML definition. Alternatively, you can use single quotes for the value to be treated as a string literal, where no escaping is necessary.