Flyway & Liquibase

Flyway e Liquibase são os dois executores de migração baseados em JVM mais comuns para PostgreSQL em pipelines empresariais. Ambos rastreiam alterações aplicadas, suportam CI e integram-se com Spring e orquestração de releases.

Receita

# Flyway
flyway -url=jdbc:postgresql://localhost:5432/myapp \
  -user=app_migrator -password="$DB_PASS" \
  -locations=filesystem:db/migration \
  migrate
 
# Liquibase
liquibase --url=jdbc:postgresql://localhost:5432/myapp \
  --username=app_migrator --password="$DB_PASS" \
  --changeLogFile=db/changelog/db.changelog-master.yaml \
  update

Quando usar isso: Múltiplos alvos de deploy, requisitos de auditoria, validação de checksum e equipes já padronizadas em ferramentas JVM.

Exemplo de Trabalho

Layout do Flyway:

db/migration/
  V1__baseline.sql
  V2__add_orders.sql
  V3__orders_index_concurrent.sql  # nota: executar fora da transação - ver docs

-- V2__add_orders.sql
SET ROLE app_owner;
CREATE TABLE app.orders (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  total_cents integer NOT NULL
);
RESET ROLE;

Changelog mestre do Liquibase:

# db/changelog/db.changelog-master.yaml
databaseChangeLog:
  - include:
      file: changes/001-baseline.sql
      relativeToChangelogFile: true
  - include:
      file: changes/002-orders.yaml
      relativeToChangelogFile: true

# changes/002-orders.yaml
databaseChangeLog:
  - changeSet:
      id: 002-orders
      author: data-team
      changes:
        - sqlFile:
            path: 002-orders.sql
            relativeToChangelogFile: true
      rollback:
        - sql: DROP TABLE IF EXISTS app.orders;

O que isso demonstra:

• Flyway: um arquivo SQL por versão, nomenclatura linear V{n}__
• Liquibase: changelog YAML/XML com blocos de rollback opcionais por changeSet
• Ambos registram o histórico em tabelas de metadados automaticamente

Mergulho Profundo

Comparação

Configurações Específicas do PostgreSQL

# flyway.conf
flyway.postgresql.transactional.lock=false
flyway.cleanDisabled=true

# Liquibase changeSet para índice CONCORRENTE
- changeSet:
    id: idx-concurrent
    runInTransaction: false
    changes:
      - sql:
          sql: CREATE INDEX CONCURRENTLY idx_orders_created ON app.orders (created_at);

• CREATE INDEX CONCURRENTLY não pode ser executado em uma transação.
• Desative clean no Flyway de produção - ele remove todos os objetos.
• Use lock_timeout e statement_timeout no SQL de migração (veja regras de segurança).

Integração CI

flyway validate   # detecção de desvio de checksum
flyway info       # pendente vs aplicado
liquibase status
liquibase validate

Armadilhas

• Editar arquivo de migração aplicado - Incompatibilidade de checksum bloqueia o deploy. Correção: Nova migração direta V4__fix.sql, nunca reescreva V2.
• Índice concorrente dentro da transação - O padrão do Flyway envolve em transação; a migração falha. Correção: executeInTransaction=false por migração (Flyway) ou runInTransaction: false (Liquibase).
• Baixa confiança no rollback do Liquibase - SQL de rollback não testado apodrece. Correção: Trate o rollback como apenas para simulação; prefira correções diretas de expansão/contração.
• Migrador superusuário - Concessões e padrões RLS incorretos. Correção: app_migrator com SET ROLE app_owner.
• Histórico diferente por ambiente - Hotfix selecionado apenas em produção. Correção: Mesmo SHA do git através do pipeline dev/staging/prod.

Alternativas

FAQs

Relacionados

• Princípios de Migração - princípios de SQL versionado
• DDL de Zero Downtime - operações concorrentes
• Estratégia de Rollback - política apenas direta

Versões do Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.