Um guia para retornos de chamada Flyway
1. Introdução
A biblioteca Flyway permite a versão dos bancos de dados, rastreando as alterações armazenadas como código-fonte SQL. Each set of changes is referred to as a migration.
Migrações individuais são aplicadas a um banco de dados sequencialmente usando um conjunto de comandos que incluemmigrate,clean, info, validate,baselineerepair. Eles são aplicados de maneira controlada, de acordo com a versão atual do banco de dados de destino.
Embora as migrações sejam geralmente suficientes para cobrir a maioria dos casos de uso, há vários cenários adequados para retornos de chamada.
Neste artigo, usaremos callbacks do Flyway para se conectar ao ciclo de vida dos vários comandos que ele fornece.
2. Cenários de caso de uso
Podemos ter um requisito muito específico que requer o tipo de flexibilidade oferecida pelos retornos de chamada. Aqui estão alguns casos de uso possíveis:
-
Rebuilding materialized views – podemos quererrebuild materialized views sempre que aplicamos migrações que afetam as tabelas base dessas visualizações. Os retornos de chamada SQL são uma boa opção para executar esse tipo de lógica
-
Flushing a cache – talvez tenhamos uma migração que modifica os dados que estão armazenados em cache. Podemos usar callbacks paraflush caches, certificando-se de que nosso aplicativo extraia dados novos do banco de dados
-
Calling an external system – usando callbacks, podemoscall out to an external system usando uma tecnologia arbitrária. Por exemplo, podemos querer publicar um evento, enviar um email ou acionar a reinicialização do servidor
3. Callbacks suportados
Há um retorno de chamadabefore eafter correspondente para cada um dos comandos Flyway disponíveis. Para obter mais informações sobre esses comandos, consulteour main Flyway article ouofficial documentation.
The name of each callback consists of either before or after, followed by the command name.
Por exemplo, os callbacks para o comandoclean sãobeforeCleaneafterClean. Os retornos de chamada são acionados imediatamente antes e após a execução.
Lembrando o que discutimos na introdução, esses comandos são:migrate,clean, info, validate,baselineerepair.
Além dos retornos de chamadabeforeeafter para cada comando, existem 2 retornos de chamada adicionais disponíveis para o comandomigrate. Esses retornos de chamada são chamados debeforeEachMigrate eafterEachMigrate.
O comandomigrate apresenta esses retornos de chamada adicionais porque geralmente é o caso de executar o comandomigrate na execução de muitas migrações.
Os autores do Flyway forneceram esses ganchos adicionais para nos dar controle da lógica de retorno de chamada personalizada com o mais alto nível de granularidade com o qual o Flyway trabalha, ou seja, a migração individual.
4. Dependências
Para ver como os callbacks funcionam na prática, vamos trabalhar com um exemplo simples. Podemos começar com nosso exemplo declarando flyway-core como uma dependência em nossopom.xml:
org.flywaydb
flyway-core
5.0.2
Podemos encontrar as versões mais recentes deflyway-core emMaven Central.
5. Retornos de chamada
O Flyway nos permite criar retornos de chamada usando duas abordagens diferentes, Java ou SQL. O primeiro é o mais flexível. Ele nos oferece a liberdade de executar código arbitrário.
O último nos permite interagir diretamente com o banco de dados.
5.1. Retornos de chamada em Java
The Java API contract is defined in the FlywayCallback interface. Por conveniência, umBaseFlywayCallback é fornecido, o qual é padronizado para uma implementação no-op para cada método.
No caso mais simples, implementar um retorno de chamada envolve estenderBaseFlywayCallback e substituir o (s) método (s) desejado (s) como em nossoExampleFlywayCallback:
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. Retornos de chamada SQL
The SQL callback contract is defined by using files with specific names contained in directories that are configured as locations(s). Flyway procurará em seulocations(s) configurado por arquivos de retorno de chamada SQL e os executará adequadamente.
Por exemplo, um arquivo denominadobeforeEachMigrate.sql em um diretório configurado comolocation seria executado antes de cada script de migração durante a execução do comandomigrate.
6. Configuração e Execução
No exemplo a seguir, configuramos nosso retorno de chamada Java e especificamos dois locais de script SQL: um contendo nossas migrações e o outro contendo retornos de chamada SQL.
Não é necessário configurar locais separados para migrações e retornos de chamada SQL, mas configuramos dessa forma em nosso exemplo para demonstrar como eles podem ser mantidos separados:
@Test
public void migrateWithSqlAndJavaCallbacks() {
Flyway flyway = new Flyway();
flyway.setDataSource(dataSource);
flyway.setLocations("db/migration", "db/callbacks");
flyway.setCallbacks(new ExampleFlywayCallback());
flyway.migrate();
}Se definirmos umbeforeEachMigrate em Java e SQL, é útil saber que o retorno de chamada Java será executado primeiro e imediatamente seguido pela execução do retorno de chamada SQL.
Isso pode ser visto na saída do teste acima:
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. Conclusão
Neste artigo, vimos como o mecanismo de retorno de chamada Flyway pode ser usado em Java e SQL. Examinamos possíveis casos de uso e detalhamos um exemplo.
Como sempre, todo o código-fonte pode ser encontradoover on GitHub.