A Guide to Flyway Callbacks – 飞禽走兽回调指南

最后修改: 2017年 12月 30日

1. Introduction


The Flyway library allows us to version databases by tracking changes stored as SQL source code. Each set of changes is referred to as a migration.


Individual migrations are applied to a database sequentially using a set of commands which include migrate, clean, info, validate, baseline and repair. They are applied in a controlled manner according to the current version of the target database.

单独的迁移是通过一组命令按顺序应用于数据库的,这些命令包括migrate, clean, info, validate, baselinerepair。它们是根据目标数据库的当前版本以受控的方式应用的。

While migrations are usually sufficient to cover most use cases, there are a number of scenarios that are well-suited for callbacks.


In this article, we’ll use Flyway callbacks to hook into the life-cycle for the various commands it provides.


2. Use Case Scenarios


We may have a very specific requirement that requires the sort of flexibility offered by callbacks. Here are a few possible use cases:


  • Rebuilding materialized views – we might want to rebuild materialized views whenever we apply migrations affecting the base tables of those views. SQL callbacks are a good fit for executing this type of logic
  • Flushing a cache – perhaps we have a migration that modifies data that happens to be cached. We can use callbacks to flush caches making sure that our application pulls fresh data from the database
  • Calling an external system – using callbacks, we can call out to an external system using an arbitrary technology. For example, we might want to publish an event, send an email, or trigger a server restart

3. Supported Callbacks


There’s a corresponding before and after callback event for each of the available Flyway commands. For more information on these commands, refer to our main Flyway article, or the official documentation.

对于每个可用的 Flyway 命令,都有相应的 beforeafter 回调事件。有关这些命令的更多信息,请参阅我们的主要Flyway文章,或官方文档

  • BEFORE_ events are fired before the operation is executed.
  • AFTER_ events are fired after the operation has succeeded. These after events also have a couple of more granular events:
    • ERROR equivalents are fired after the operation has failed.
    • OPERATION_FINISH events are fired after the operation has finished.
  • migrate and undo also have _EACH event which is fired for each individual migration. The migrate and undo command features these additional callbacks because it’s often the case that running these commands results in the execution of many migrations.

The complete list of callback events can be found in the Event class.


For example, the callback events for the clean command are BEFORE_CLEAN and AFTER_CLEAN. Flyway fires them immediately before and after the clean command execution.


Recalling what we discussed in the introduction, available commands are: migrate, clean, info, validate, baseline and repair.

回顾我们在介绍中讨论的内容,可用的命令有。migrate, clean, info, validate, baseline and repair

The authors of Flyway provided these additional hooks to give us control of custom callback logic at the highest level of granularity that Flyway works with, that is, the individual migration.


4. Dependencies


To see how the callbacks work in practice, let’s work through a simple example. We can get started with our example by declaring flyway-core as a dependency in our pom.xml:



We can find the latest versions of flyway-core on Maven Central.

我们可以在Maven Central上找到flyway-core的最新版本。

5. Callbacks


Flyway enables us to create callbacks using two different approaches, Java, or SQL. The former is the most flexible one. It provides us with the freedom to execute arbitrary code.


The latter lets us interact with the database directly.


5.1. Java Callbacks


The Java API contract is defined in the Callback interface.

Java API合约是在Callback接口中定义的。

In the simplest case, to create a custom callback we need to implement the Callback interface, as in our ExampleFlywayCallback:


public class ExampleFlywayCallback implements Callback {

    private final Log log = LogFactory.getLog(getClass());

    public boolean supports(Event event, Context context) {
        return event == Event.AFTER_EACH_MIGRATE;

    public boolean canHandleInTransaction(Event event, Context context) {
        return true;

    public void handle(Event event, Context context) {
        if (event == Event.AFTER_EACH_MIGRATE) {
            log.info("> afterEachMigrate");

    public String getCallbackName() {
        return ExampleFlywayCallback.class.getSimpleName();

5.2. SQL Callbacks


The SQL callback contract is defined by using files with specific names contained in directories that are configured as locations(s). Flyway will look in its configured locations(s) for SQL callback files and execute them accordingly.

SQL回调合同是通过使用包含在被配置为locations(s)目录中的具有特定名称的文件来定义的。 Flyway将在其配置的locations(s)中寻找SQL回调文件并相应地执行它们。

As an example, a file named beforeEachMigrate.sql in a directory configured as a location would run before each migration script during the execution of the migrate command.


6. Configuration and Execution


In the following example, we configure our Java callback and we specify two SQL script locations: one containing our migrations and the other containing SQL callbacks.


It isn’t necessary to configure separate locations for migrations and SQL callbacks, but we set it up this way in our example to demonstrate how these can be kept separate:


public void migrateWithSqlAndJavaCallbacks() {
    Flyway flyway = Flyway.configure()
      .locations("db/migration", "db/callbacks")
      .callbacks(new ExampleFlywayCallback())

If we define a beforeEachMigrate in both Java and SQL, it’s helpful to know that the Java callback will be executed first and immediately followed by the execution of the SQL callback.


This can be seen in the output from the above test:


21:50:45.677 [main] INFO  c.b.f.FlywayApplicationUnitTest - > migrateWithSqlAndJavaCallbacks
21:50:45.848 [main] INFO  o.f.c.i.license.VersionPrinter - Flyway Community Edition 8.0.0 by Redgate
21:50:45.849 [main] INFO  o.f.c.i.d.base.BaseDatabaseType - Database: jdbc:h2:mem:DATABASE (H2 1.4)
21:50:45.938 [main] INFO  o.f.core.internal.command.DbValidate - Successfully validated 2 migrations (execution time 00:00.021s)
21:50:45.951 [main] INFO  o.f.c.i.s.JdbcTableSchemaHistory - Creating Schema History table "PUBLIC"."flyway_schema_history" ...
21:50:46.003 [main] INFO  o.f.c.i.c.SqlScriptCallbackFactory - Executing SQL callback: beforeMigrate - 
21:50:46.015 [main] INFO  o.f.core.internal.command.DbMigrate - Current version of schema "PUBLIC": << Empty Schema >>
21:50:46.023 [main] INFO  o.f.c.i.c.SqlScriptCallbackFactory - Executing SQL callback: beforeEachMigrate - 
21:50:46.024 [main] INFO  o.f.core.internal.command.DbMigrate - Migrating schema "PUBLIC" to version "1.0 - add table one"
21:50:46.025 [main] INFO  c.b.f.ExampleFlywayCallback - > afterEachMigrate
21:50:46.046 [main] INFO  o.f.c.i.c.SqlScriptCallbackFactory - Executing SQL callback: beforeEachMigrate - 
21:50:46.046 [main] INFO  o.f.core.internal.command.DbMigrate - Migrating schema "PUBLIC" to version "1.1 - add table two"
21:50:46.047 [main] INFO  c.b.f.ExampleFlywayCallback - > afterEachMigrate
21:50:46.067 [main] INFO  o.f.core.internal.command.DbMigrate - Successfully applied 2 migrations to schema "PUBLIC", now at version v1.1 (execution time 00:00.060s)

7. Conclusion


In this article, we looked at how the Flyway callback mechanism can be used in both Java and SQL. We looked at possible use cases and detailed an example.


As always, all source code can be found over on GitHub.