Versioned Migration Scripts

If a Versioned Migration Script has not been deployed to any permanent downstream environments, then it is easy to rename it.  Use the blue folder in the upper right to open the project on disk.  Go into the migrations folder and rename the file from there.  You can now commit and push your changes with this new filename. 

If a Versioned Migration Script has been deployed to one or more permanent downstream environments, then it's best not to change the name because this changes the history of what was deployed to that environment.  Sometimes, the name is truly wrong and we do want to fix this though.  If that's the case, read on.

A migration script is made up of 4 parts:

1. Prefix
2. Version Number (followed by 2 underscores)
3. Description
4. File extension

Example: Prefix<Version>__<Description>.sql → V002_20230434023243__NewProcForEmployeeUpdates.sql

Renaming the description

If you want to rename the description, you can do that on disk and re-commit, but this does not update the recorded description in the tracking table on the target, the flyway_schema_history table.  The value in there will still be the old name, which may cause confusion and will fail future migrations.  To fix this, run flyway repair on each target environment that the script has already been applied to.

Renaming the version

If you want to rename the version and this script has already been applied to 1 or more environments, you'll need to update the version information in the flyway_schema_history table on each target where the script has run.  The reason is because the version number uniquely identifies the script.  If you change the version number, the original script will have a Missing state and the script with the new number will look like it's a new migration script and show as Pending in the target environment even though it has already been applied.  Trying to migrate will fail validation, and if you skip validating on Migrate, the flyway migrate command might still fail since the script might not be idempotent.  

If you must change it, you'll need to update the version information in the downstream flyway_schema_history tables to reflect this change.  A flyway repair is NOT needed since the version column is not included in the checksum validation calculation.

Note: We don't recommending touching the flyway_schema_history table directly.  Please make sure you have a backup in case anything goes wrong.

If you want to rename the version just because you want to change the order the scripts are applied, there may be other options:

• Use outOfOrder=true (the default for projects created in Flyway Desktop) and branches to deploy the scripts you want when you want in any order; make sure you have a good automated testing process in place and a staging environment for production to make sure there are no dependency/order issues, if you do change the order they are applied. 
• Use cherryPick and outOfOrder=true (the default for projects created in Flyway Desktop) to explicitly list the order the V scripts should run.

If you have any questions about this, please get in touch with the Development Team.