Environments are a set of associated properties used to connect to a database.

The concept of an environment has been created to allow Flyway to work easily with several different databases or configurations from a single configuration file.

Environment names

Environment names are case-sensitive, so Prod and prod are separate environments, and selecting an environment with the environment setting requires the exact casing.

Flyway warns if you configure environments whose names differ only by case, as this is likely to cause confusion. We recommend giving each environment a distinct name.

Environment settings

Deprecated settings

Environment namespaces

TOML Configuration

These parameters should be configured in an environments namespace.

[environments.example]
url = "jdbc:sqlite:local_database1.db"
username = "bob"
...
[environments.another_example]
url = "jdbc:sqlite:local_database2.db"
username = "jeff"
...
[environments.another_example]
locations = ["defaultLocation","customLocation"]

Resolvers

Usually you won't want to keep sensitive information in a plain text configuration file and so resolvers can be used to pull information into your configuration from a variety of external sources like environment variables and secrets managers.

Command line configuration

It is possible to define an environment on the commandline, for example:

./flyway info -environments.example.url=jdbc:sqlite:local_database.db -environment=example

Note: You define an environment using the environments (plural) namespace but you specify which environment to use with the environment (singular) parameter.

Environment Variables

Any environment setting can be set for a specific named environment using an OS environment variable of the form environments_{environment name}_{setting}:

environments_example_url=jdbc:sqlite:local_database.db
environments_example_password=mysecretpassword

Settings in a nested namespace (such as flyway or jdbcProperties) are addressed the same way, with an extra _ per level:

environments_example_flyway_locations=filesystem:./sql1,filesystem:./sql2
environments_example_jdbcProperties_accessToken=mytoken

The environments_ prefix is case-insensitive, so ENVIRONMENTS_EXAMPLE_PASSWORD is an equally valid way of setting the same value. This only extends to the prefix itself and to setting names backed by a Java field (which are matched case-insensitively). It does not extend to nested key-value settings such as jdbcProperties, whose keys are passed through to the JDBC driver verbatim and may be case-sensitive: ENVIRONMENTS_EXAMPLE_JDBCPROPERTIES_ACCESSTOKEN would be sent to the driver as accesstoken, not accessToken, so nested settings still need their exact casing.

Combining environment definitions

An environment with the same name can be defined in more than one place, such as in several configuration files, in environment variables and on the command line. Flyway merges these definitions setting by setting, rather than one definition replacing another, so a setting defined in only one place is kept.

Where the same setting is defined in more than one place, the value is chosen according to Configuration Precedence. Between configuration files, the file loaded last takes precedence.

For example, with these two configuration files:

# flyway1.toml
[environments.sample]
url = "jdbc:sqlite:file1.db"
connectRetries = 10

# flyway2.toml
[environments.sample]
url = "jdbc:sqlite:file2.db"

Running with -configFiles="flyway1.toml,flyway2.toml" results in the sample environment using the URL jdbc:sqlite:file2.db with connectRetries set to 10.

Legacy configuration

Properties that were originally part of the regular flyway configuration (-url, -user, -password) can still be used for backwards compatibility. Flyway applies them to the current environment, as selected by the environment setting, overriding any values that environment already has. If no environment is selected, this is the environment named default.