Руководство по обратным вызовам Flyway

1. Введение

Библиотека Flyway позволяет нам создавать версии баз данных, отслеживая изменения, хранящиеся в виде исходного кода SQL. Каждый набор изменений называется миграцией .

Отдельные миграции применяются к базе данных последовательно с помощью набора команд, включающих migrate , clean, info, validate, baseline и repair . Они применяются контролируемым образом в соответствии с текущей версией целевой базы данных.

Хотя миграций обычно достаточно для покрытия большинства случаев использования, существует ряд сценариев, которые хорошо подходят для обратных вызовов.

В этой статье мы будем использовать обратные вызовы Flyway для подключения к жизненному циклу различных команд, которые он предоставляет.

2. Сценарии использования

У нас может быть очень специфическое требование, требующее гибкости, предлагаемой обратными вызовами. Вот несколько возможных вариантов использования:

• Перестроение материализованных представлений — нам может понадобиться перестраивать материализованные представления всякий раз, когда мы применяем миграции, влияющие на базовые таблицы этих представлений. Обратные вызовы SQL хорошо подходят для выполнения этого типа логики.
• Очистка кеша — возможно, у нас есть миграция, которая изменяет данные, которые оказались в кеше. Мы можем использовать обратные вызовы для очистки кешей , чтобы убедиться, что наше приложение извлекает свежие данные из базы данных.
• Вызов внешней системы — с помощью обратных вызовов мы можем вызывать внешнюю систему с использованием произвольной технологии. Например, мы можем захотеть опубликовать событие, отправить электронное письмо или инициировать перезагрузку сервера.

3. Поддерживаемые обратные вызовы

Для каждой из доступных команд Flyway существует соответствующее событие обратного вызова до и после . Подробнее об этих командах читайте в нашей основной статье Flyway , или в официальной документации .

• События BEFORE_ запускаются до выполнения операции.

• События AFTER_ запускаются после успешного выполнения операции. Эти афтер -события также имеют несколько более детальных событий:

• Эквиваленты ERROR запускаются после сбоя операции.

• События OPERATION_FINISH запускаются после завершения операции.

• миграция и отмена также имеют событие _EACH, которое запускается для каждой отдельной миграции. Команда migrate и undo содержит эти дополнительные обратные вызовы, потому что выполнение этих команд часто приводит к выполнению множества миграций.

Полный список событий обратного вызова можно найти в классе Event .

Например, событиями обратного вызова для команды очистки являются BEFORE_CLEAN и AFTER_CLEAN . Flyway запускает их непосредственно до и после выполнения чистой команды.

Вспоминая то, что мы обсуждали во введении, доступны следующие команды: migrate , clean, info, validate, baseline и repair .

Авторы Flyway предоставили эти дополнительные крючки, чтобы дать нам контроль над пользовательской логикой обратного вызова на самом высоком уровне детализации, с которым работает Flyway, то есть на индивидуальной миграции.

4. Зависимости

Чтобы увидеть, как обратные вызовы работают на практике, давайте рассмотрим простой пример. Мы можем начать работу с нашим примером, объявив flyway-core как зависимость в нашем pom.xml :

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

Последние версии flyway-core мы можем найти на Maven Central .

5. Обратные вызовы

Flyway позволяет нам создавать обратные вызовы, используя два разных подхода: Java или SQL. Первый является наиболее гибким. Это дает нам свободу выполнять произвольный код.

Последний позволяет нам напрямую взаимодействовать с базой данных.

5.1. Обратные вызовы Java

Контракт Java API определяется в интерфейсе обратного вызова .

В самом простом случае для создания пользовательского обратного вызова нам нужно реализовать интерфейс обратного вызова , как в нашем 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

Контракт обратного вызова SQL определяется с помощью файлов с определенными именами, содержащихся в каталогах, настроенных как местоположения . Flyway будет искать в своих настроенных местоположениях файлы обратного вызова SQL и выполнять их соответствующим образом.

Например, файл с именем beforeEachMigrate.sql в каталоге, сконфигурированном как расположение , будет запускаться перед каждым сценарием миграции во время выполнения команды migrate .

6. Конфигурация и выполнение

В следующем примере мы настраиваем наш обратный вызов Java и указываем два местоположения сценария SQL: одно, содержащее наши миграции, и другое, содержащее обратные вызовы SQL.

Нет необходимости настраивать отдельные местоположения для миграций и обратных вызовов SQL, но мы настроили их таким образом в нашем примере, чтобы продемонстрировать, как их можно хранить отдельно:

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

Если мы определим beforeEachMigrate как в Java, так и в SQL, полезно знать, что обратный вызов Java будет выполнен первым, а сразу после него будет выполнен обратный вызов SQL.

Это можно увидеть на выходе из приведенного выше теста:

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. Заключение

В этой статье мы рассмотрели, как можно использовать механизм обратного вызова Flyway как в Java, так и в SQL. Мы рассмотрели возможные варианты использования и подробно описали пример.

Как всегда, весь исходный код можно найти на GitHub .