This feature is available in Flyway Teams or Flyway Enterprise.

Scenarios

If you ever needed to limit a script to run in a certain environment or when a certain placeholder is set, then this feature is for you. The following examples are common use cases for this:

This is a test script. We want it to run in our 'Test' environment, but not in any other environments.
We deploy to many different clients. Sometimes, we have to write bespoke scripts for a certain client. These scripts should only run on 'Prod-ClientA' and nowhere else.
If you wrote a migration script for a certain feature, but you're not ready to release that feature yet so you don't want the script to run in any downstream environments yet, but you still want to commit it for your team to review.

Deploy Rules Overview

The Flyway Teams/Enterprise command line has had the capability to restrict a scripts execution. Each migration script can have a script configuration file (which lives in the same directory) with conditions for when the script should execute using the shouldExecute expression. This is now exposed in the Flyway Desktop GUI as Deploy Rules.

The Deploy Rules applied to each script will appear on the Migrations scripts tab in the Migrations table. In this example, the Development database is selected as the target on the right. The Test1 and Test2 migration scripts have Deploy Rules that specify only execute if the environment is develop or target1 respectively. Since the Development database is the selected target, Test1 script has a status of Pending, and Test2 is ignored. The pending migration script will be applied to the target database if you ran the migrate command.

Following running the migrate command, Test1 successfully ran against develop and Test2 was ignored as intended.

It is possible to add/edit Deploy Rules after your Migration Script has been saved. On the Migrations scripts, tab click on the Migration in the Migrations table to view the script at the bottom. You can then add/edit/remove deploy rules and update the shouldExecute expression.

Note: Changing a Deploy Rule will not have any impact if the script has already been executed against an environment and there will not be a checksum warning on Flyway validation.

Note: Changing the shouldExecute expression directly in the script config file must be done with the Migration preview pane closed, otherwise it will get overwritten by what's in the Flyway Desktop GUI.

For more information on the shouldExecute configuration option, see shouldExecute configuration documentation.

Deploy Rules How To: Limiting Migration Script Deployment Examples

There are various ways to limit script deployment, editing the shouldExecute parameter or editing your migration script in the Migrations view as above. See below for different deployment needs:

Don't run the migration script
Only run migration script in certain environments
Only run migration script under certain placeholder conditions
Always run migration

(1) Don't run the migration script

If you are in a scenario where you don't want to run a migration script (<migration>.sql file) under any conditions, you can do this one of two ways:

Edit <migration>.sql.conf file and set to false:
1. ```
shouldExecute=false
```
In the Migrations view, add/edit the custom rule and enter 'false' in the Rule expression box

(2) Only run migration script in certain environments

Configured Environments

For environments that are already configured in your Flyway desktop project, select the environments you want the migration to run against in the dropdown in the Migration script view:

Custom Environments

If you want to run the migration script against environments that aren't configured in the project, you will need to edit the shouldExecute parameter in <migration>.sql.conf file:

shouldExecute=${flyway.environment}==custom

This will appear in the dropdown in the Migration script view. If deselected, it will be removed from the dropdown and removed from the shouldExecute parameter because it's not an environment configured to the project.

It is possible to include multiple environments that you want the script to run in:

shouldExecute=(${flyway:environment==dev}||${flyway:environment}==custom)

This will show in the dropdown with dev and custom environments selected:

Note: Please ensure this environment exists outside of the project. Otherwise the migration will run against the environment, which is not what you were expecting.

(3) Only run migration script under certain placeholder conditions

If you want to run migration related to feature A, for example, perform the following steps:

Either: set the custom rule through the migration preview Deploy Rules OR set the custom rule using the shouldExecute expression in <migration>.sql.conf file:

OR

shouldExecute=(${flyway:environment==dev)&&featureA==true

2. Set the placeholder value in e.g. the project .toml file:

featureA=true

Toggle this value so that if you want the migration script with the custom rule to run, it's set to true, but if you don't want it to run, set it too false.

CI/CD Pipeline Placeholder Usage

If you want to set a placeholder value in your CI/CD pipeline, you can run migrations with the placeholder value set via the command line.

flyway -placeholders.featureA=true migrate

For more detail on placeholders see here: Placeholder Configuration

(4) Always run migration

If Deploy Rules are not configured for a migration script, then that migration script will NOT have a script config file and it will run on any environment when it's pending.