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

最后修改: 2017年 12月 30日

中文/混合/英文(键盘快捷键：t)

1. Introduction

1.介绍

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.

Flyway库允许我们通过跟踪存储为SQL源代码的变化来对数据库进行版本管理。每一组变化被称为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, baseline 和repair。它们是根据目标数据库的当前版本以受控的方式应用的。

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.

在这篇文章中，我们将使用Flyway的回调来钩住它所提供的各种命令的生命周期。

2. Use Case Scenarios

2.用例情景

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

3.支持的回调

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 命令，都有相应的 before 和 after 回调事件。有关这些命令的更多信息，请参阅我们的主要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.

回调事件的完整列表可以在Event类中找到。

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.

例如，clean命令的回调事件是BEFORE_CLEAN和AFTER_CLEAN。Flyway在执行clean命令之前和之后会立即触发这些事件。

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.

Flyway的作者提供了这些额外的钩子，使我们能够在Flyway工作的最高粒度水平上控制自定义回调逻辑，也就是个别迁移。

4. Dependencies

4.依赖性

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:

为了了解回调在实践中是如何工作的，让我们通过一个简单的例子。我们可以通过在pom.xml中声明flyway-core为依赖项来开始我们的例子。

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

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

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

5. Callbacks

5.回调

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.

Flyway使我们能够使用两种不同的方法来创建回调，即Java，或SQL。前者是最灵活的一种。它为我们提供了执行任意代码的自由。

The latter lets us interact with the database directly.

后者让我们与数据库直接互动。

5.1. Java Callbacks

5.1.Java回调[/strong]

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:

在最简单的情况下，要创建一个自定义回调，我们需要实现回调接口，就像我们的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

5.2.SQL回调

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.

作为一个例子，在配置为location的目录中，一个名为beforeEachMigrate.sql的文件将在执行migrate命令时在每个迁移脚本之前运行。

6. Configuration and Execution

6.配置和执行

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.

在下面的例子中，我们配置了我们的Java回调，并指定了两个SQL脚本位置：一个包含我们的迁移，另一个包含SQL回调。

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:

我们没有必要为迁移和SQL回调配置不同的位置，但是我们在例子中这样设置是为了演示如何将这些东西分开。

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

如果我们在Java和SQL中都定义了一个beforeEachMigrate，那么知道Java回调将被首先执行，紧接着执行SQL回调是很有帮助的。

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

7.结论

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.

在这篇文章中，我们研究了如何在Java和SQL中使用Flyway回调机制。我们研究了可能的用例，并详细介绍了一个例子。

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

一如既往，所有源代码都可以在GitHub上找到。