flyway-callbacks

Posted on: 2019-10-08 2019-11-19
Tags: Flyway

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 for each of the available Flyway commands. For more information on these commands, refer to our main Flyway article, or the official documentation.

The name of each callback consists of either before or after, followed by the command name.

For example, the callbacks for the clean command are beforeClean and afterClean. Callbacks are fired immediately before and after the execution.

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

In addition to the before and after callbacks for each command, there are 2 additional callbacks available for the migrate command. These callbacks are named beforeEachMigrate and afterEachMigrate.

The migrate command features these additional callbacks because it’s often the case that running the migrate command results in the execution of many migrations.

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>5.0.2</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 FlywayCallback interface. For convenience, a BaseFlywayCallback is provided which defaults to a no-op implementation for each method.

In the simplest case, implementing a callback involves extending BaseFlywayCallback and overriding the desired method(s) as in our ExampleFlywayCallback:

public class ExampleFlywayCallback extends BaseFlywayCallback {

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

    @Override
    public void afterEachMigrate(Connection connection, MigrationInfo info) {
        log.info("> afterEachMigrate");
    }

    // other methods
}

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 = new Flyway();
    flyway.setDataSource(dataSource);
    flyway.setLocations("db/migration", "db/callbacks");
    flyway.setCallbacks(new ExampleFlywayCallback());
    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 execution of the SQL callback.

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

2017-12-18 08:16:17,413 [main] INFO  c.b.f.FlywayApplicationTest - > migrateWithSqlAndJavaCallbacks
... // other log messages
2017-12-18 08:16:17,494 [main] INFO  o.f.core.internal.command.DbMigrate -
  <strong>Migrating schema "PUBLIC" to version 1.0 - add table one</strong>
2017-12-18 08:16:17,494 [main] INFO  c.b.f.ExampleFlywayCallback - > beforeEachMigrate
2017-12-18 08:16:17,494 [main] INFO  o.f.c.i.c.SqlScriptFlywayCallback -
  <strong>Executing SQL callback: beforeEachMigrate</strong>
2017-12-18 08:16:17,495 [main] INFO  c.b.f.ExampleFlywayCallback - > afterEachMigrate
2017-12-18 08:16:17,499 [main] INFO  o.f.core.internal.command.DbMigrate -
  <strong>Migrating schema "PUBLIC" to version 1.1 - add table two</strong>
2017-12-18 08:16:17,500 [main] INFO  c.b.f.ExampleFlywayCallback - > beforeEachMigrate
2017-12-18 08:16:17,500 [main] INFO  o.f.c.i.c.SqlScriptFlywayCallback -
  <strong>Executing SQL callback: beforeEachMigrate</strong>
2017-12-18 08:16:17,501 [main] INFO  c.b.f.ExampleFlywayCallback - > afterEachMigrate
2017-12-18 08:16:17,505 [main] INFO  o.f.core.internal.command.DbMigrate -
  <strong>Successfully applied 2 migrations to schema "PUBLIC"</strong> (execution time 00:00.020s).

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.

getdocs

3043