Flyway

Callback concept

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.


Didn't find what you were looking for?