Gerador de Liquibase changelog a partir de tabela

Changelogs do Liquibase: migrations abstratas e portáveis

O Liquibase é a ferramenta de migration de banco criada por Nathan Voxland em 2006, hoje mantida pela Liquibase, Inc. Enquanto o Flyway rastreia arquivos SQL crus, o Liquibase modela cada mudança como um changeset abstrato em XML, YAML, JSON ou SQL. O runner traduz a descrição abstrata em SQL específico do dialeto na hora da execução — é por isso que o mesmo changelog funciona contra PostgreSQL, MySQL, Oracle, SQL Server, Snowflake e mais de 50 outros engines.

É distribuído como CLI open-source mais a camada paga Liquibase Pro (relatórios avançados, pipelines Liquibase Flow) e o Liquibase Hub (descontinuado em 2023). Integra com Maven, Gradle, Spring Boot (spring-boot-starter-liquibase), Docker, Jenkins, GitHub Actions e a maioria dos sistemas de CI.

Anatomia de um changeset

Um changelog é uma lista de elementos <changeSet>, cada um identificado pelo par id + author. O formato XML é o original; o YAML é mais legível e cada vez mais preferido:

<changeSet id="1" author="alice">
  <createTable tableName="users">
    <column name="id" type="uuid">
      <constraints primaryKey="true"/>
    </column>
    <column name="email" type="varchar(255)">
      <constraints unique="true" nullable="false"/>
    </column>
  </createTable>
</changeSet>

O Liquibase converte type="uuid" na coluna correta para o dialeto (UUID no PostgreSQL, CHAR(36) no MySQL, UNIQUEIDENTIFIER no SQL Server). Ainda é possível descer para SQL cru com <sql> ou <sqlFile path="..."/> quando faltar abstração.

Rollback, contexts, labels e preconditions

• Rollback — todo changeset pode declarar o inverso via <rollback>. Para operações conhecidas (createTable, addColumn), o Liquibase gera o inverso automaticamente.
• Contexts — marque um changeset com context="dev,test" para aplicá-lo apenas em ambientes selecionados.
• Labels — semelhante a contexts mas combinado com expressões booleanas para seleção mais rica.
• Preconditions — condicionam a execução a um check (<columnExists>, <sqlCheck>) para pular ou abortar quando o banco está em um estado inesperado.

O Liquibase grava as mudanças aplicadas na tabela DATABASECHANGELOG (e bloqueia o schema com DATABASECHANGELOGLOCK durante a execução para impedir migrations concorrentes).

Liquibase vs Flyway

• Abstração — Liquibase abstrai o dialeto; Flyway é SQL cru. Escolha Liquibase para portabilidade multi-banco real.
• Rollback — first-class no Liquibase open-source; só na versão comercial do Flyway.
• Verbosidade — Flyway é mais enxuto; YAML/XML do Liquibase carrega metadados mesmo em mudanças triviais.
• Tooling — ambos têm integrações fortes com Spring Boot, Maven e CI. Ambos podem ser executados a partir de um container Docker.

Alternativas emergentes a partir de 2023 incluem Atlas, Bytebase e abordagens schema-as-code que comparam um arquivo de estado desejado com o banco vivo — filosofia diferente, vale avaliar em projetos novos.

FAQ

Usar XML ou YAML? YAML pela legibilidade e menor ruído. XML ainda aparece em projetos legados e na documentação. JSON é raramente escolhido.

Posso misturar SQL cru em um changelog YAML? Sim — use o change type sql ou sqlFile apontando para um arquivo separado. Misture à vontade.

Liquibase ou Flyway — qual escolher? Liquibase se você mira em vários bancos ou precisa de rollback nativo. Flyway se o time prefere SQL cru e fica em um único engine.

O que acontece se eu editar um changeset já commitado? O Liquibase recalcula o MD5 e se recusa a rodar com erro de validation failed. Adicione um novo changeset com um novo id em vez de editar.

Spring Boot integra nativamente? Sim — adicione spring-boot-starter-liquibase, coloque o changelog em src/main/resources/db/changelog/ e as migrations rodam no startup.