Руководство по обратным вызовам Flyway
1. Вступление
Библиотека Flyway позволяет нам создавать версии баз данных, отслеживая изменения, хранящиеся в исходном коде SQL. Each set of changes is referred to as a migration.с
Отдельные миграции применяются к базе данных последовательно с использованием набора команд, который включаетmigrate,clean, info, validate,baseline иrepair. Они применяются контролируемым образом в соответствии с текущей версией целевой базы данных.
Хотя миграций обычно достаточно, чтобы покрыть большинство случаев использования, существует ряд сценариев, которые хорошо подходят для обратных вызовов.
В этой статье мы будем использовать обратные вызовы Flyway, чтобы подключиться к жизненному циклу различных команд, которые он предоставляет.
2. Сценарии использования
У нас может быть очень конкретное требование, которое требует такой гибкости, которую обеспечивают обратные вызовы. Вот несколько возможных вариантов использования:
-
Rebuilding materialized views – мы можем захотеть использоватьrebuild materialized views всякий раз, когда мы применяем миграции, затрагивающие базовые таблицы этих представлений. Обратные вызовы SQL хорошо подходят для выполнения логики этого типа
-
Flushing a cache –, возможно, у нас есть миграция, которая изменяет данные, которые случайно кэшируются. Мы можем использовать обратные вызовы дляflush caches, чтобы убедиться, что наше приложение извлекает свежие данные из базы данных.
-
Calling an external system – с помощью обратных вызовов, мы можемcall out to an external system с использованием произвольной технологии. Например, мы можем опубликовать событие, отправить электронное письмо или запустить перезапуск сервера.
3. Поддерживаемые обратные вызовы
Для каждой из доступных команд Flyway существует соответствующий обратный вызовbefore иafter. Для получения дополнительной информации об этих командах обратитесь кour main Flyway article илиofficial documentation.
The name of each callback consists of either before or after, followed by the command name.
Например, обратными вызовами для командыclean являютсяbeforeClean иafterClean. Обратные вызовы запускаются непосредственно до и после выполнения.
Вспоминая то, что мы обсуждали во введении, это команды:migrate,clean, info, validate,baseline иrepair.
Помимо обратных вызововbefore иafter для каждой команды, для командыmigrate доступны 2 дополнительных обратных вызова. Эти обратные вызовы называютсяbeforeEachMigrate иafterEachMigrate.
Командаmigrate содержит эти дополнительные обратные вызовы, потому что часто выполнение командыmigrate приводит к выполнению множества миграций.
Авторы Flyway предоставили эти дополнительные возможности, чтобы дать нам контроль над пользовательской логикой обратного вызова на самом высоком уровне детализации, с которым работает Flyway, то есть с индивидуальной миграцией.
4. зависимости
Чтобы увидеть, как обратные вызовы работают на практике, давайте рассмотрим простой пример. Мы можем начать с нашего примера, объявив flyway-core как зависимость в нашемpom.xml:
org.flywaydb
flyway-core
5.0.2
Мы можем найти последние версииflyway-core наMaven Central.
5. Callbacks
Flyway позволяет нам создавать обратные вызовы, используя два разных подхода: Java или SQL. Первый самый гибкий. Это дает нам свободу выполнять произвольный код.
Последнее позволяет нам напрямую взаимодействовать с базой данных.
5.1. Java Callbacks
The Java API contract is defined in the FlywayCallback interface. Для удобства предоставляетсяBaseFlywayCallback, который по умолчанию является реализацией без операций для каждого метода.
В простейшем случае реализация обратного вызова включает расширениеBaseFlywayCallback и переопределение желаемого метода (ов), как в нашем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
The SQL callback contract is defined by using files with specific names contained in directories that are configured as locations(s). Flyway будет искать в своем настроенномlocations(s) файлы обратного вызова SQL и выполнять их соответствующим образом.
Например, файл с именемbeforeEachMigrate.sql в каталоге, настроенном какlocation, будет запускаться перед каждым сценарием миграции во время выполнения командыmigrate.
6. Конфигурация и исполнение
В следующем примере мы настраиваем наш обратный вызов Java и указываем два местоположения сценария SQL: одно содержит наши миграции, а другое содержит обратные вызовы SQL.
Нет необходимости настраивать отдельные местоположения для миграций и обратных вызовов SQL, но мы настроили это в нашем примере, чтобы продемонстрировать, как их можно разделить:
@Test
public void migrateWithSqlAndJavaCallbacks() {
Flyway flyway = new Flyway();
flyway.setDataSource(dataSource);
flyway.setLocations("db/migration", "db/callbacks");
flyway.setCallbacks(new ExampleFlywayCallback());
flyway.migrate();
}Если мы определяемbeforeEachMigrate как в Java, так и в SQL, полезно знать, что обратный вызов Java будет выполнен первым, а за ним сразу же последует выполнение обратного вызова SQL.
Это можно увидеть в выводе из вышеприведенного теста:
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 -
Migrating schema "PUBLIC" to version 1.0 - add table one
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 -
Executing SQL callback: beforeEachMigrate
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 -
Migrating schema "PUBLIC" to version 1.1 - add table two
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 -
Executing SQL callback: beforeEachMigrate
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 -
Successfully applied 2 migrations to schema "PUBLIC" (execution time 00:00.020s).7. Заключение
В этой статье мы рассмотрели, как механизм обратного вызова Flyway можно использовать как в Java, так и в SQL. Мы рассмотрели возможные варианты использования и подробно описали пример.
Как всегда, весь исходный код можно найтиover on GitHub.