Guia de Utilização do Flyway via Pipeline

O Flyway é uma ferramenta de gerenciamento de migrações de banco de dados que automatiza o processo de aplicação de scripts SQL em um banco de dados em diferentes ambientes.

Tipos de Arquivos de Script Flyway:

  • SQL Migrations:

    • Além dos scripts SQL padrão, o Flyway também suporta scripts em outros formatos, como SQL, PL/SQL, PL/pgSQL, T-SQL, DDL, entre outros.
    • Isso permite que você use a linguagem de script mais adequada para suas necessidades específicas de banco de dados.
    • Exemplo: sql -- V2__Alter_table.sql ALTER TABLE minha_tabela ADD COLUMN novo_coluna VARCHAR(50);

  • Repeatable Scripts:

    • Esses scripts são aplicados automaticamente pelo Flyway sempre que são modificados, garantindo que a última versão do script esteja sempre aplicada no banco de dados.
    • Eles são úteis para definir objetos de banco de dados que devem ser recriados sempre que houver uma mudança no script.
    • Eles não têm um número de versão associado, em vez disso, são nomeados com um prefixo fixo, como R__Meu_Script.sql.
    • Exemplo: sql -- R__Meu_Script.sql CREATE OR REPLACE FUNCTION minha_funcao() RETURNS VOID AS $$ BEGIN -- Lógica da função END; $$ LANGUAGE plpgsql;

Configuração do Flyway:

  • Instalação: Certifique-se de que o Flyway esteja instalado no ambiente de execução do pipeline. Exemplo: bash # Instalação via Homebrew no macOS brew install flyway
  • Configuração do Banco de Dados: Defina as configurações de conexão com o banco de dados alvo no arquivo de configuração do Flyway (flyway.conf). Exemplo: properties flyway.url=jdbc:mysql://localhost:3306/my_database flyway.user=myuser flyway.password=mypassword
  • Estrutura do Projeto: Mantenha a estrutura dos scripts de migração dentro do projeto, geralmente em um diretório separado (db/migration). Exemplo: db/ ├── migration/ │ ├── V1__Create_table.sql │ ├── V2__Add_column_to_table.sql │ └── ...

Integração com o Pipeline:

  • Etapa de Build: Adicione uma etapa ao pipeline de build para executar o Flyway. Isso pode ser feito através da execução do comando flyway migrate. Exemplo: bash flyway migrate

Versionamento Coeso:

  • Nomenclatura dos Scripts: Siga uma convenção de nomenclatura consistente para os scripts de migração. Use prefixos que indiquem a ordem de execução e uma descrição clara do que está sendo alterado no banco de dados. Exemplo: sql V1__Create_table.sql V2__Add_column_to_table.sql
  • Checksum: O Flyway usa um checksum para rastrear a integridade dos scripts de migração. Evite modificar scripts já aplicados no banco de dados, pois isso pode causar problemas de checksum e falhas na migração.

Correção de Scripts com Defeitos:

O Flyway permite que você modifique scripts de migração que falharam ou estão com erros sem comprometer a integridade do sistema de versionamento. Isso é feito através da introdução de subversões ou versões fracionadas nos números de versão dos scripts de migração.

Quando um script de migração falha ou precisa ser corrigido, você pode simplesmente criar uma nova versão desse script com uma subversão incremental. Aqui está como funciona:

Suponha que você tenha um script de migração original com o número de versão V1__Meu_Script.sql. Se esse script falhar ou precisar ser corrigido, você pode criar uma nova versão com uma subversão, por exemplo, V1.1__Meu_Script.sql. Neste caso, a versão principal é V1 e a subversão é .1.

Aqui estão algumas coisas importantes a se notar sobre esse método:

  1. Preservação da Ordem: As subversões devem sempre ser incrementais e mantidas na ordem correta. Por exemplo, V1.1, V1.2, V1.3, e assim por diante.

  2. Separador: A convenção do Flyway é usar dois underscores (__) como separador entre o número da versão e o nome do script.

  3. Aplicação Automática: Quando você executa o Flyway, ele irá aplicar automaticamente as subversões após a versão principal. Por exemplo, após aplicar V1, o Flyway irá aplicar V1.1, V1.2, e assim por diante, se existirem.

  4. Integridade do Sistema de Versionamento: Esse método permite que você mantenha a integridade do sistema de versionamento, pois as alterações são rastreadas de forma incremental e não há conflitos entre os scripts.

Ao usar subversões, você pode corrigir erros ou fazer ajustes em scripts de migração sem precisar modificar as versões principais, garantindo assim a coesão e a integridade do processo de migração.

É importante seguir estas etapas ao corrigir um erro de script:

  • Identificação de Problemas: Ao detectar um problema em um script de migração (por exemplo, erro de sintaxe ou resultado diferente do esperado), identifique o problema o mais rápido possível.
  • Correção Localmente: Corrija o script de migração localmente em seu ambiente de desenvolvimento.
  • Criação de Novo Script: Se o script original já foi aplicado em ambientes de produção, crie um novo script de migração corrigido com um número de versão superior ao script original. Por exemplo, se o script problemático for V2__Add_column_to_table.sql, o novo script poderia ser V3__Correcao_Add_column_to_table.sql.
  • Teste Local: Teste o novo script de migração localmente em diferentes ambientes de desenvolvimento, garantindo que ele produza o resultado esperado.
  • Execução no Pipeline: Adicione o novo script de migração ao repositório e execute o pipeline de CI/CD para aplicar a correção em todos os ambientes necessários.

Boas Práticas:

  • Scripts Atômicos: Mantenha os scripts de migração atômicos, ou seja, cada script deve representar uma única alteração no banco de dados.
  • Testes de Migração: Realize testes automatizados para garantir que os scripts de migração funcionem conforme o esperado em diferentes ambientes.
  • Documentação: Documente os scripts de migração, explicando as alterações que estão sendo feitas e qualquer pré-requisito ou impacto nos dados existentes.

O Que Evitar:

  • Scripts Destrutivos: Evite escrever scripts que possam causar perda de dados ou destruição de esquemas existentes no banco de dados.
  • Scripts Dependentes de Estado: Evite depender do estado atual do banco de dados nos scripts de migração. Eles devem ser autocontidos e não devem confiar em condições específicas do ambiente.
  • Alterações Manuais: Evite fazer alterações manuais diretamente no banco de dados que não estejam refletidas nos scripts de migração. Isso pode levar a inconsistências entre os ambientes de desenvolvimento, teste e produção.

Seguindo essas práticas, você poderá usar o Flyway de forma eficaz em seu pipeline de integração contínua, mantendo o versionamento coeso e garantindo a consistência do banco de dados em diferentes ambientes.