CI/CD de migração de schema (Flyway/Liquibase)

Sintoma

Objetivo: gerenciar as alterações de schema do banco com arquivos de migração versionados; aplicá-las de forma automática, mas controlada, no CI/CD com Flyway ou Liquibase.

1. Crie arquivos de migração versionados (Vxxx__nome.sql)

Escreva cada alteração de schema em um arquivo nomeado com número de versão crescente; a convenção do Flyway é V<versão>__<descrição>.sql (ex.: V1__initial_schemas.sql, V2__orders_table.sql). Esses arquivos ficam no Git e são aplicados em ordem de versão. As migrações aplicadas são registradas em uma tabela de controle (flyway_schema_history no Flyway), então cada migração roda exatamente uma vez.

PostgreSQL

-- V2__orders_table.sql
CREATE TABLE orders (
  id       bigserial PRIMARY KEY,
  amount    numeric(12,2) NOT NULL,
  created_at   timestamptz DEFAULT now()
);

2. Preserve a imutabilidade com checksums

O Flyway/Liquibase guardam o checksum de cada migração aplicada. Se você editar depois um arquivo já aplicado, o checksum não confere mais e a ferramenta falha. Regra: NUNCA edite uma migração aplicada; faça a correção com um novo arquivo de versão. Isso garante que todos os ambientes (dev/staging/prod) compartilhem o mesmo histórico.

PostgreSQL

# repair on checksum mismatch (use with care):
flyway repair
# the right way: add the change in a new Vx file

3. Faça o baseline de um banco existente

Use baseline ao ligar a ferramenta de migração a um banco já populado e sem histórico; ele trata o estado atual como 'versão inicial' e não tenta recriar os objetos existentes. As migrações após baselineVersion são aplicadas. Em um ambiente criado do zero não é preciso baseline; as migrações rodam a partir da V1.

PostgreSQL

flyway baseline -baselineVersion=1 -baselineDescription="existing schema"

4. Migre automaticamente no pipeline de CI

Rode a ferramenta de migração em uma etapa de CI para aplicar as alterações automaticamente nos bancos de teste e staging; o comando migrate roda apenas os arquivos novos (não aplicados) e é idempotente. Aplicar a migração primeiro em um banco temporário/efêmero e validá-la pega SQL quebrado antes de chegar à produção. O schema precisa ser migrado ANTES do deploy do código da aplicação (com alterações retrocompatíveis).

PostgreSQL

# CI step (Flyway)
flyway -url=jdbc:postgresql://staging/appdb \
  -user=ci -password=$PW migrate

MySQL

flyway -url=jdbc:mysql://staging/appdb \
  -user=ci -password=$PW migrate

5. Adicione uma etapa de aprovação manual para produção

Teste/staging são automáticos, mas faça o migrate em produção exigir aprovação manual; adicione uma etapa de 'approval gate' (aprovação manual) no CI/CD. Antes da aprovação, mostre quais migrações vão rodar com 'flyway info' ou 'liquibase status'. Sempre faça um backup recente antes de aplicar em produção para poder voltar atrás se algo der errado.

PostgreSQL

# what will run before approval?
flyway info
# liquibase equivalent:
liquibase status --verbose

6. Defina a reversibilidade e uma estratégia de rollback

O Flyway Community não tem undo automático; adote o princípio de migração somente para frente: em vez de desfazer um erro, escreva uma nova migração que o corrija. Changesets do Liquibase podem definir um bloco de rollback e ser revertidos com 'liquibase rollback'. A estratégia mais robusta: mantenha as alterações pequenas e retrocompatíveis, faça backup antes de operações arriscadas (remoção de colunas) e prepare um plano de rollback por escrito.

PostgreSQL

-- Liquibase rollback example (inside a changeset)
--changeset dev:2
CREATE TABLE orders (...);
--rollback DROP TABLE orders;