Capítulo 4: Migração com Liquibase

Introdução

Liquibase é uma alternativa popular ao Flyway. Enquanto o Flyway utiliza principalmente SQL puro, o Liquibase oferece um formato agnóstico de banco de dados (XML, YAML, JSON) que pode ser convertido em SQL para diferentes bancos de dados.

🎯 Objetivos do Capítulo

Ao final deste capítulo, você saberá:

✅ Compreender as diferenças entre Flyway e Liquibase
✅ Configurar Liquibase com Spring Boot
✅ Criar changelogs em XML, YAML e SQL
✅ Utilizar rollbacks automáticos
✅ Escolher entre Flyway e Liquibase

1. Flyway vs Liquibase

Comparação Rápida

Aspecto	Flyway	Liquibase
Formato principal	SQL nativo	XML, YAML, JSON, SQL
Curva de aprendizado	Muito fácil	Média
Portabilidade multi-BD	Baixa (SQL específico)	Alta
Rollback	Manual	Automático para algumas operações
Comunidade	Muito ampla	Ampla
Spring Boot	Excelente integração	Excelente integração

Quando Escolher Flyway?

✅ Use Flyway se:

Você utiliza apenas um banco de dados
Prefere SQL nativo
Busca máxima simplicidade
Sua equipe domina SQL

Quando Escolher Liquibase?

✅ Use Liquibase se:

Precisa suportar múltiplos bancos de dados (PostgreSQL, MySQL, Oracle...)
Deseja rollbacks automáticos
Prefere formatos declarativos (YAML, XML)
Tem mudanças complexas para gerenciar

2. Instalação

Dependência Maven

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

cuidado

Atenção: Não utilize Flyway e Liquibase juntos no mesmo projeto!

3. Estrutura de Arquivos

Estrutura Recomendada

src/
└── main/
    └── resources/
        └── db/
            └── changelog/
                ├── db.changelog-master.xml    # Arquivo principal
                ├── changes/
                │   ├── 001-create-users.xml
                │   ├── 002-add-email.xml
                │   └── 003-create-orders.xml
                └── data/
                    └── initial-data.xml       # Dados iniciais

Arquivo Master (Ponto de Entrada)

<!-- db.changelog-master.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <!-- Incluir arquivos de mudanças -->
    <include file="db/changelog/changes/001-create-users.xml"/>
    <include file="db/changelog/changes/002-add-email.xml"/>
    <include file="db/changelog/changes/003-create-orders.xml"/>
    
    <!-- Ou incluir uma pasta inteira -->
    <includeAll path="db/changelog/data/"/>

</databaseChangeLog>

4. Formato XML

Criar uma Tabela

<!-- 001-create-users.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <changeSet id="1" author="dev">
        <comment>Criar a tabela users</comment>
        
        <createTable tableName="users">
            <column name="id" type="BIGINT" autoIncrement="true">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="username" type="VARCHAR(50)">
                <constraints nullable="false" unique="true"/>
            </column>
            <column name="password" type="VARCHAR(100)">
                <constraints nullable="false"/>
            </column>
            <column name="created_at" type="TIMESTAMP" defaultValueComputed="CURRENT_TIMESTAMP"/>
        </createTable>
        
        <!-- Rollback automático: DROP TABLE users -->
    </changeSet>

</databaseChangeLog>

Adicionar uma Coluna

<!-- 002-add-email.xml -->
<databaseChangeLog ...>

    <changeSet id="2" author="dev">
        <comment>Adicionar a coluna email</comment>
        
        <addColumn tableName="users">
            <column name="email" type="VARCHAR(100)">
                <constraints unique="true"/>
            </column>
        </addColumn>
        
        <!-- Rollback automático: DROP COLUMN email -->
    </changeSet>

</databaseChangeLog>

Criar um Índice

<changeSet id="3" author="dev">
    <createIndex tableName="users" indexName="idx_users_email">
        <column name="email"/>
    </createIndex>
</changeSet>

Inserir Dados

<changeSet id="4" author="dev">
    <insert tableName="users">
        <column name="username" value="admin"/>
        <column name="password" value="$2a$10$hashedpassword"/>
        <column name="email" value="admin@example.com"/>
    </insert>
    
    <!-- Rollback manual necessário -->
    <rollback>
        DELETE FROM users WHERE username = 'admin';
    </rollback>
</changeSet>

5. Formato YAML

Muito mais legível que XML!

Criar uma Tabela

# 001-create-users.yaml
databaseChangeLog:
  - changeSet:
      id: 1
      author: dev
      comment: Criar a tabela users
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: BIGINT
                  autoIncrement: true
                  constraints:
                    primaryKey: true
                    nullable: false
              - column:
                  name: username
                  type: VARCHAR(50)
                  constraints:
                    nullable: false
                    unique: true
              - column:
                  name: password
                  type: VARCHAR(100)
                  constraints:
                    nullable: false
              - column:
                  name: created_at
                  type: TIMESTAMP
                  defaultValueComputed: CURRENT_TIMESTAMP

Adicionar uma Coluna

# 002-add-email.yaml
databaseChangeLog:
  - changeSet:
      id: 2
      author: dev
      comment: Adicionar email em users
      changes:
        - addColumn:
            tableName: users
            columns:
              - column:
                  name: email
                  type: VARCHAR(100)
                  constraints:
                    unique: true

Arquivo Master em YAML

# db.changelog-master.yaml
databaseChangeLog:
  - include:
      file: db/changelog/changes/001-create-users.yaml
  - include:
      file: db/changelog/changes/002-add-email.yaml
  - includeAll:
      path: db/changelog/data/

6. Formato SQL (Como Flyway)

Você também pode usar SQL puro:

-- 001-create-users.sql
-- liquibase formatted sql

-- changeset dev:1
-- comment: Criar a tabela users
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    password VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- rollback DROP TABLE users;

-- 002-add-email.sql
-- liquibase formatted sql

-- changeset dev:2
ALTER TABLE users ADD COLUMN email VARCHAR(100) UNIQUE;

-- rollback ALTER TABLE users DROP COLUMN email;

7. Configuração Spring Boot

Configuração Mínima

# application.properties
spring.liquibase.enabled=true
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml

Configuração Completa

# Ativar Liquibase
spring.liquibase.enabled=true

# Arquivo principal de changelog
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.yaml

# Schemas
spring.liquibase.default-schema=public
spring.liquibase.liquibase-schema=public

# Contextos (dev, test, prod)
spring.liquibase.contexts=dev

# Labels
spring.liquibase.labels=

# Rollback em caso de falha
spring.liquibase.rollback-file=rollback.sql

Formato YAML

spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.yaml
    default-schema: public
    contexts: dev

8. Rollbacks

Rollback Automático

Liquibase gera automaticamente rollbacks para:

Operação	Rollback Automático
createTable	DROP TABLE
addColumn	DROP COLUMN
createIndex	DROP INDEX
addForeignKey	DROP FOREIGN KEY
insert	❌ (manual)
update	❌ (manual)
delete	❌ (manual)
sql	❌ (manual)

Rollback Manual

<changeSet id="5" author="dev">
    <update tableName="users">
        <column name="status" value="ACTIVE"/>
        <where>status IS NULL</where>
    </update>
    
    <!-- Rollback manual obrigatório -->
    <rollback>
        <update tableName="users">
            <column name="status" valueComputed="NULL"/>
            <where>status = 'ACTIVE'</where>
        </update>
    </rollback>
</changeSet>

Executar um Rollback

# Rollback do último changeset
mvn liquibase:rollback -Dliquibase.rollbackCount=1

# Rollback até uma tag
mvn liquibase:rollback -Dliquibase.rollbackTag=v1.0

# Rollback até uma data
mvn liquibase:rollback -Dliquibase.rollbackDate=2025-01-01

9. Contextos e Labels

Contextos

Executar certos changesets apenas em determinados ambientes:

<!-- Apenas em dev -->
<changeSet id="10" author="dev" context="dev">
    <insert tableName="users">
        <column name="username" value="testuser"/>
    </insert>
</changeSet>

<!-- Apenas em prod -->
<changeSet id="11" author="dev" context="prod">
    <insert tableName="config">
        <column name="key" value="feature.flag"/>
        <column name="value" value="true"/>
    </insert>
</changeSet>

# application-dev.properties
spring.liquibase.contexts=dev

# application-prod.properties
spring.liquibase.contexts=prod

Labels

Agrupar changesets por funcionalidade:

<changeSet id="20" author="dev" labels="user-feature">
    <!-- Mudanças relacionadas a usuários -->
</changeSet>

<changeSet id="21" author="dev" labels="order-feature">
    <!-- Mudanças relacionadas a pedidos -->
</changeSet>

10. A Tabela DATABASECHANGELOG

Liquibase rastreia as mudanças em uma tabela:

SELECT * FROM DATABASECHANGELOG;

ID	AUTHOR	FILENAME	DATEEXECUTED	ORDEREXECUTED	EXECTYPE	MD5SUM	DESCRIPTION
1	dev	001-create-users.xml	2025-01-15	1	EXECUTED	abc123	createTable tableName=users
2	dev	002-add-email.xml	2025-01-15	2	EXECUTED	def456	addColumn tableName=users

11. Comandos Maven

<plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <configuration>
        <propertyFile>src/main/resources/liquibase.properties</propertyFile>
    </configuration>
</plugin>

# Ver status
mvn liquibase:status

# Aplicar mudanças
mvn liquibase:update

# Gerar o SQL sem executar
mvn liquibase:updateSQL

# Rollback
mvn liquibase:rollback -Dliquibase.rollbackCount=1

# Criar uma tag
mvn liquibase:tag -Dliquibase.tag=v1.0

# Gerar um changelog a partir de um banco existente
mvn liquibase:generateChangeLog

12. Resumo

Pontos-Chave

Conceito	Descrição
ChangeLog	Arquivo principal que lista as mudanças
ChangeSet	Uma mudança atômica (id + author únicos)
Contextos	Filtrar changesets por ambiente
Labels	Agrupar changesets por funcionalidade
Rollback	Desfazer mudanças (auto ou manual)

Quando Usar Qual Ferramenta?

Configuração Mínima

# application.yml com Liquibase
spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.yaml

Arquivo Master Mínimo

# db.changelog-master.yaml
databaseChangeLog:
  - includeAll:
      path: db/changelog/changes/

🎯 Próximo Passo

Agora você já tem toda a teoria! É hora de praticar com os exercícios práticos.

➡️ TP7.1: Configuração de Datasource e Pool

⬅️ Voltar ao Módulo 7

Introdução​

🎯 Objetivos do Capítulo​

1. Flyway vs Liquibase​

Comparação Rápida​

Quando Escolher Flyway?​

Quando Escolher Liquibase?​

2. Instalação​

Dependência Maven​

3. Estrutura de Arquivos​

Estrutura Recomendada​

Arquivo Master (Ponto de Entrada)​

4. Formato XML​

Criar uma Tabela​

Adicionar uma Coluna​

Criar um Índice​

Inserir Dados​

5. Formato YAML​

Criar uma Tabela​

Adicionar uma Coluna​

Arquivo Master em YAML​

6. Formato SQL (Como Flyway)​

7. Configuração Spring Boot​

Configuração Mínima​

Configuração Completa​

Formato YAML​

8. Rollbacks​

Rollback Automático​

Rollback Manual​

Executar um Rollback​

9. Contextos e Labels​

Contextos​

Labels​

10. A Tabela DATABASECHANGELOG​

11. Comandos Maven​

12. Resumo​

Pontos-Chave​

Quando Usar Qual Ferramenta?​

Configuração Mínima​

Arquivo Master Mínimo​

🎯 Próximo Passo​

Introdução

🎯 Objetivos do Capítulo

1. Flyway vs Liquibase

Comparação Rápida

Quando Escolher Flyway?

Quando Escolher Liquibase?

2. Instalação

Dependência Maven

3. Estrutura de Arquivos

Estrutura Recomendada

Arquivo Master (Ponto de Entrada)

4. Formato XML

Criar uma Tabela

Adicionar uma Coluna

Criar um Índice

Inserir Dados

5. Formato YAML

Criar uma Tabela

Adicionar uma Coluna

Arquivo Master em YAML

6. Formato SQL (Como Flyway)

7. Configuração Spring Boot

Configuração Mínima

Configuração Completa

Formato YAML

8. Rollbacks

Rollback Automático

Rollback Manual

Executar um Rollback

9. Contextos e Labels

Contextos

Labels

10. A Tabela DATABASECHANGELOG

11. Comandos Maven

12. Resumo

Pontos-Chave

Quando Usar Qual Ferramenta?

Configuração Mínima

Arquivo Master Mínimo

🎯 Próximo Passo