Migration Command Dry Runs
Published 03 January 2025
EDITION: TEAMS
When Flyway migrates a database, it looks for migrations that need to be applied, sorts them and applies them in order directly against the database.
There are situations where you may want to
- preview the changes Flyway will make to the database
- submit the SQL statements for review to a DBA before applying them
- use Flyway to determine what needs updating, yet use a different tool to apply the actual database changes
Flyway Teams Edition gives you a way to achieve all these scenarios using Dry Runs.
How it works
Dry runs can be configured by setting the flyway.dryRunOutput property on the migrate command, or some other Flyway commands. As soon as this property is set, Flyway kicks in dry run mode. The database is no longer modified and all SQL statements that would have been applied are sent to the dry run output instead.
When doing a migrate Dry Run, Flyway sets up a read-only connection to the database. It assesses what migrations need to run and generates a single SQL file containing all statements it would have executed in case of a regular migration run. This SQL file can then be reviewed. If satisfactory, Flyway can then be instructed to migrate the database and all changes will be applied. This SQL file also contains the necessary statements to create and update Flyway's schema history table, ensuring that all schema changes are tracked the usual way.
It is not advised to change a dry run script after it's been generated. Instead, any changes should be made to the migrations and a new dry run script generated. This is to ensure the changes executed match what's in your migrations.
It is not recommended to execute the dry run script directly without using Flyway, as there are some Flyway features which are not handled by the dry run script (see limitations below). If you do need to execute a deployment without using Flyway, you can use the Prepare command.
Limitations
These changes are intercepted and written into a file as explained above.
- SQL versioned migrations
- SQL repeatable migrations
- SQL callbacks
These are not executed during a dry run. Instead, their file names are logged in the dry run output.
Tutorial
Click here to see a tutorial on using dry runs.
