Entendendo Flyway

Nota: Isto não é um artigo, são minhas anotações de estudo sobre o que é o Flyway, que resolvi postar.

O Flyway é uma ferramenta de versionamento de banco de dados.
Ele ajuda a controlar e aplicar mudanças no esquema do banco (migrations) de forma segura e automatizada — assim como o Git controla versões de código. Ele é específico para banco de dados relacionais.

Scripts

Você cria arquivos SQL chamados migrations. Cada um representa uma mudança no banco. Eles seguem uma convenção de nome:

V1__create_message_table.sql
V2__create_room_table.sql

V é de versão e o número (1, 2) diz a ordem em que devem ser executados.

Tabela de controle

Quando o Flyway roda pela primeira vez, ele cria uma tabela dentro do seu banco, chamada por padrão de:

flyway_schema_history

Essa tabela guarda o histórico de todas as migrações aplicadas.

Execução

Quando a aplicação inicia (ou quando você roda o comando flyway migrate), o Flyway faz o seguinte:

1. Lê todos os arquivos de migração disponíveis na pasta configurada (por exemplo, db/migration/);
2. Compara com a tabela flyway_schema_history do banco;
3. Executa apenas os scripts que ainda não foram aplicados, em ordem crescente de versão. ### Controle de integridade O Flyway guarda também um checksum (hash) de cada script. Se alguém altera um script antigo (por exemplo, muda V2__create_room_table.sql depois de aplicado), o Flyway detecta a diferença e gera erro — pra evitar inconsistência entre versões do banco. ### Repetição e rollback As migrations são pensadas para serem irreversíveis (você cria novas versões em vez de apagar ou alterar antigas). Se precisar “voltar atrás”, cria um novo script que desfaz a alteração anterior (em vez de alterar o antigo). ## Spring Boot O Spring Boot detecta automaticamente o Flyway durante a inicialização se o projeto tiver a dependência no pom.xml. ### Inicialização Quando o Spring Boot inicia, ele faz algo nesta ordem:
4. Cria a conexão com o banco (DataSource).
5. Antes de carregar seus repositórios, entidades JPA, etc., ele chama o Flyway.
6. O Flyway:
   • Cria (se não existir) a tabela flyway_schema_history.
   • Procura por scripts na pasta padrão classpath:db/migration/.
   • Aplica os que ainda não estão marcados como executados.
   • Só depois disso o Spring continua inicializando o restante da aplicação. Isso garante que o banco já esteja na versão certa antes de qualquer entidade JPA tentar interagir com ele.

Dentro do projeto você cria algo assim:

src
└── main
    ├── java/...
    └── resources
        └── db
            └── migration
                ├── V1__create_table_users.sql
                ├── V2__add_column_email.sql
                └── V3__insert_initial_data.sql

Cada arquivo é uma migration. Quando a aplicação sobe, o Flyway lê esses arquivos e aplica o que falta.

Configuração do application.properties

Você pode personalizar a configuração:

spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration
spring.flyway.baseline-on-migrate=true
spring.flyway.user=postgres
spring.flyway.password=1234
spring.flyway.url=jdbc:postgresql://localhost:5432/meubanco