Executing scripts before or after deployment via callbacks
Published 17 September 2025
Hooking into deployment process
It is possible to use callbacks to hook into the deployment process and define scripts that you want to execute before or after every deployment.
It is also possible to add conditions to these callbacks if there are circumstances where they shouldn't run.
For a complete list of callback events see Callback events.
State-based deployment
For state-based deployments, use the beforeDeploy, afterDeploy, and afterDeployError callbacks.
Migrations-based deployment
For migrations-based deployments use the beforeMigrate, afterMigrate, and afterMigrateError callbacks if using the migrate command.
It is also possible to use prepare and deploy commands for migrations, in which case deploy callbacks can be used.
Discovery
Flyway discovers script callbacks from one or more directories, classpath locations, or cloud storage locations, referenced by the callbackLocations property.
If the callbackLocations property is not set, Flyway will look for them in the configured locations setting, in the same folder as your migrations. Note that deploy callbacks will never be read from the locations property, but only from the callbackLocations property.
Once you have configured the callback locations you want to use, Flyway will automatically pick up any scripts conforming to the callback naming convention.
This scanning is recursive. All callbacks in non-hidden directories/packages below the specified ones are also picked up.
Java callbacks will be picked up from the classpath.
SQL Callbacks
The most convenient way to hook into Flyway's lifecycle is through SQL callbacks. These are simply sql files in the configured locations following a certain naming convention: the event name followed by the SQL migration suffix.
SQL callbacks are executed in their own transactions, distinct from the transactions used for executing SQL in flyway commands.
Placeholder replacement works just like it does for SQL migrations.
Optionally the callback may also include a description. In that case the callback name is composed of the event name, the separator, the description and the suffix. Example: beforeRepair__vacuum.sql.
Note: Flyway will also honor any sqlMigrationSuffixes you have configured, when scanning for SQL callbacks.
Java Callbacks
If SQL Callbacks aren't flexible enough for you, you have the option to implement the Callback interface yourself. You can even hook multiple Callback implementations in the lifecycle. Java callbacks have the additional flexibility that a single Callback implementation can handle multiple lifecycle events, and are therefore not bound by the SQL callback naming convention.
More info: Java-based Callbacks
Script Callbacks
Much like SQL callbacks, Flyway also supports the execution of callbacks written in a scripting language. The supported file extensions are the same as those supported by script migrations. For example, you could have a beforeRepair__vacuum.ps1 callback. Script callbacks give you much more flexibility and power during the migration lifecycle. Some of the things you can achieve are:
- Executing external tools between migrations
- Creating or cleaning local files for migrations to use
Callback ordering
When multiple callbacks for the same event are found, they are executed in the alphanumerical order. E.G.
beforeConnect__1.sql
beforeConnect__2.sql
beforeConnect__a.sql
beforeConnect__b.sql
