In Flyway an environment is a set of associated properties used to connect to a database. You might have a development environment, representing your development database, a production environment representing your production database, and any other environments you need Flyway to be able to connect to, depending upon how you have set up your database pipeline.

You might also define temporary environments for temporary databases used in validation such as build or shadow databases.

Whenever you fill out a connection dialog in Flyway Desktop, the environment configuration will be saved to disk.

For the full list of configuration file properties see the reference documentation.

For more guidance on connecting to environments, see Connecting to environments.

Example configuration

[environments.development]
url = "jdbc:sqlite:development.db"
username = "bob"

[environments.production]
url = "jdbc:sqlite:production.db"
username = "jeff"

Environment id

Each environment has a unique id. This can be configured in the id field in Flyway Desktop (note that the development and shadow databases id are pre-set and not editable in the UI). In the TOML configuration file, the id is present in the TOML table name. i.e. for an environment defined as [environments.development], the environment id is development.

When running a command using the Flyway command line which applies to a single database, all that needs adding to the command line is -environment={id}. This can be added to the configuration file if there is a desire for a default target for flyway commands.

Default environment

Many flyway commands target a single environment, configured using the environment setting., If this is not set, it will be assumed that there is an environment called default. If you import a .conf project to a TOML project, any environment parameters such as url will be added under [environments.default]. Adding the environment setting to the TOML config file with a new value changes the default environment.

Resolvers

Usually you wouldn'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.

Provisioning

It is possible to provision a database which does not exist yet before connecting to it, or potentially to re-provision an existing database, restoring the database back to a known state.

Reprovisioning

Re-provisioning consists of resetting a database to a known state. This could be cleaning it and leaving it empty or resetting it to a populated state, such as a snapshot of production.

Re-provisioning is currently only triggered programmatically or via Flyway Desktop. In Flyway Desktop it is triggered for the shadow database whenever the state is stale and needs to be reset. In this context, if it is used to reset to a baseline state, then it avoids the need for generating and executing a baseline migration script, which can be tricky with databases which have cross-database dependencies, or are very large.

Clean

Clean is a specific type of reprovisioning which drops all objects in a database. In addition to being configurable in the same way as provisioning, it can be run explicitly using the Clean command.

Cleaning additional objects

For complicated database structures an accurate dependency graph cannot always be constructed, so not every object is cleaned. There are also objects that we do not drop as they aren’t always safe to, for example, users in SQL Server. To clean additional objects, you can add an afterClean Callbacks defining drop statements. For example afterClean.sql:

DROP USER test_user

Configuration overrides

In addition to environment connection information, it is also possible to configure environment overrides for a lot of flyway configurations (example below).

See the reference documentation for more information.

[environments.development]
url = "jdbc:sqlite:development.db"
username = "bob"

[environments.development.flyway]
locations = ["migrations", "tests"]

[environments.production]
url = "jdbc:sqlite:production.db"
username = "jeff"

[environments.development.flyway]
locations = ["migrations"]