A Guide to Flyway Callbacks

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.

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.

• 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.

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:

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>9.16.3</version>
</dependency>

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

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.

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());

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

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

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

    @Override
    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.

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:

@Test
public void migrateWithSqlAndJavaCallbacks() {
    Flyway flyway = Flyway.configure()
      .dataSource(dataSource)
      .locations("db/migration", "db/callbacks")
      .callbacks(new ExampleFlywayCallback())
      .load();
    flyway.migrate();
}

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.