Callback concept
Published 16 November 2022
Callbacks
While migrations are sufficient for most needs, there are certain situations that require you to execute the same action over and over again. This could be recompiling procedures, updating materialized views and many other types of housekeeping.
For this reason, Flyway offers you the possibility to hook into its lifecycle by using Callbacks. In order to use these callbacks, name a script after the callback name (ie. afterMigrate.sql) and drop it alongside your other scripts in your migrations folder. Flyway will then invoke it when the execution event criteria listed below is met.
These are the events Flyway supports:
| Migrate | Execution |
|---|---|
| beforeMigrate | Before Migrate runs |
| beforeRepeatables | Before all repeatable migrations during Migrate |
| beforeEachMigrate | Before every single migration during Migrate |
| beforeEachMigrateStatement | Before every single statement of a migration during Migrate |
| afterEachMigrateStatement | After every single successful statement of a migration during Migrate |
| afterEachMigrateStatementError | After every single failed statement of a migration during Migrate |
| afterEachMigrate | After every single successful migration during Migrate |
| afterEachMigrateError | After every single failed migration during Migrate |
| afterMigrate | After successful Migrate runs |
| afterMigrateApplied | After successful Migrate runs where at least one migration has been applied |
| afterVersioned | After all versioned migrations during Migrate |
| afterMigrateError | After failed Migrate runs |
| Undo | Execution |
|---|---|
| beforeUndo Flyway Teams |
Before Undo runs |
| beforeEachUndo Flyway Teams |
Before every single migration during Undo |
| beforeEachUndoStatement Flyway Teams |
Before every single statement of a migration during Undo |
| afterEachUndoStatement Flyway Teams |
After every single successful statement of a migration during Undo |
| afterEachUndoStatementError Flyway Teams |
After every single failed statement of a migration during Undo |
| afterEachUndo Flyway Teams |
After every single successful migration during Undo |
| afterEachUndoError Flyway Teams |
After every single failed migration during Undo |
| afterUndo Flyway Teams |
After successful Undo runs |
| afterUndoError Flyway Teams |
After failed Undo runs |
| Clean | Execution |
|---|---|
| beforeClean | Before Clean runs |
| afterClean | After successful Clean runs |
| afterCleanError | After failed Clean runs |
| Info | Execution |
|---|---|
| beforeInfo | Before Info runs |
| afterInfo | After successful Info runs |
| afterInfoError | After failed Info runs |
Note: It is strongly discouraged to include any write-related callbacks for the Info command. The Info command may be internally triggered by Flyway.
| Validate | Execution |
|---|---|
| beforeValidate | Before Validate runs |
| afterValidate | After successful Validate runs |
| afterValidateError | After failed Validate runs |
| Baseline | Execution |
|---|---|
| beforeBaseline | Before Baseline runs |
| afterBaseline | After successful Baseline runs |
| afterBaselineError | After failed Baseline runs |
| Repair | Execution |
|---|---|
| beforeRepair | Before Repair runs |
| afterRepair | After successful Repair runs |
| afterRepairError | After failed Repair runs |
| Name | Execution |
|---|---|
| createSchema [deprecated, use beforeCreateSchema] | Before automatically creating non-existent schemas |
| beforeCreateSchema | Before automatically creating non-existent schemas |
| beforeConnect Flyway Community | Before Flyway connects to the database |
Callbacks can be implemented either in SQL or in Java.
Location
Flyway will discover SQL callbacks in the same manner as SQL migration scripts, based on the locations defined.
Whereas 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.
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
Tutorial
Click here to see a tutorial on using callbacks.
