TP3 - Migração de Esquema com Flyway

Objetivos do TP

Neste TP, você irá:

1. ✅ Configurar o Flyway em um projeto Spring Boot
2. ✅ Criar scripts de migração versionados
3. ✅ Simular uma evolução de esquema de banco de dados
4. ✅ Gerenciar os dados iniciais com Flyway
5. ✅ Utilizar migrações repetíveis

Duração estimada: 1h30

---

Contexto

Você está desenvolvendo uma aplicação de e-commerce. Com o tempo, o esquema evolui:

1. V1: Criação das tabelas básicas (users, products)
2. V2: Adição de colunas (email em users)
3. V3: Criação da tabela orders
4. V4: Adição de índices para performance
5. V5: Inserção de dados de referência

---

Parte 1: Configuração do Projeto

1.1 Criar o Projeto

Crie um novo projeto Spring Boot com:

• Artifact: flyway-demo
• Dependências:
  • Spring Web
  • Spring Data JPA
  • H2 Database
  • PostgreSQL Driver
  • Flyway Migration
  • Lombok

1.2 Dependências Maven

<!-- pom.xml - Verifique se o Flyway está presente -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

<!-- Para PostgreSQL (opcional) -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
</dependency>

1.3 Estrutura de Pastas

src/main/resources/
├── application.properties
├── application-dev.properties
├── application-prod.properties
└── db/
    └── migration/
        ├── V1__create_users_table.sql
        ├── V2__add_email_to_users.sql
        ├── V3__create_products_table.sql
        ├── V4__create_orders_table.sql
        ├── V5__add_indexes.sql
        ├── V6__insert_reference_data.sql
        └── R__create_views.sql

1.4 Configuração

# application.properties
spring.profiles.active=dev

# Flyway
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration
spring.flyway.baseline-on-migrate=false

# Logging
logging.level.org.flywaydb=DEBUG

# application-dev.properties
spring.datasource.url=jdbc:h2:mem:flywaydb;DB_CLOSE_DELAY=-1
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

# O JPA NÃO gerencia o esquema - o Flyway faz isso!
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=true

---

Parte 2: Primeira Migração - Users

2.1 Script V1

Crie o arquivo src/main/resources/db/migration/V1__create_users_table.sql:

-- V1__create_users_table.sql
-- Criação da tabela de usuários

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    password VARCHAR(100) NOT NULL,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    CONSTRAINT uk_users_username UNIQUE (username)
);

-- Comentário para documentação
COMMENT ON TABLE users IS 'Tabela de usuários da aplicação';

2.2 Entidade Correspondente

// src/main/java/com/example/flywaydemo/model/User.java
package com.example.flywaydemo.model;

import jakarta.persistence.*;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDateTime;

@Entity
@Table(name = "users")
@Data
@NoArgsConstructor
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 50)
    private String username;

    @Column(nullable = false, length = 100)
    private String password;

    @Column(name = "first_name", length = 50)
    private String firstName;

    @Column(name = "last_name", length = 50)
    private String lastName;

    @Column(name = "created_at")
    private LocalDateTime createdAt = LocalDateTime.now();

    @Column(name = "updated_at")
    private LocalDateTime updatedAt = LocalDateTime.now();
}

2.3 Testar

# Iniciar a aplicação
mvn spring-boot:run

# Verificar os logs - você deve ver:
# Flyway Community Edition
# Successfully validated 1 migration
# Migrating schema "PUBLIC" to version "1 - create users table"
# Successfully applied 1 migration

Verificação H2:

1. Abrir http://localhost:8080/h2-console
2. URL: jdbc:h2:mem:flywaydb
3. Verificar se a tabela users existe
4. Verificar se a tabela flyway_schema_history existe

SELECT * FROM flyway_schema_history;

---

Parte 3: Evolução do Esquema

3.1 V2 - Adicionar uma Coluna

-- V2__add_email_to_users.sql
-- Adição da coluna email

ALTER TABLE users ADD COLUMN email VARCHAR(100);

-- Criar um índice no email
CREATE UNIQUE INDEX idx_users_email ON users(email);

Atualização da entidade:

// Adicionar em User.java
@Column(unique = true, length = 100)
private String email;

3.2 V3 - Nova Tabela Products

-- V3__create_products_table.sql
-- Tabela de produtos

CREATE TABLE products (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL,
    stock_quantity INT NOT NULL DEFAULT 0,
    category VARCHAR(50),
    active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    CONSTRAINT chk_price_positive CHECK (price >= 0),
    CONSTRAINT chk_stock_positive CHECK (stock_quantity >= 0)
);

// Product.java
package com.example.flywaydemo.model;

import jakarta.persistence.*;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.math.BigDecimal;
import java.time.LocalDateTime;

@Entity
@Table(name = "products")
@Data
@NoArgsConstructor
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String name;

    @Column(columnDefinition = "TEXT")
    private String description;

    @Column(nullable = false, precision = 10, scale = 2)
    private BigDecimal price;

    @Column(name = "stock_quantity", nullable = false)
    private Integer stockQuantity = 0;

    @Column(length = 50)
    private String category;

    @Column(nullable = false)
    private Boolean active = true;

    @Column(name = "created_at")
    private LocalDateTime createdAt = LocalDateTime.now();
}

3.3 V4 - Tabela Orders com FK

-- V4__create_orders_table.sql
-- Tabela de pedidos com relação para users

CREATE TABLE orders (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT NOT NULL,
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    status VARCHAR(20) DEFAULT 'PENDING',
    total_amount DECIMAL(12, 2) NOT NULL,
    shipping_address TEXT,
    
    CONSTRAINT fk_orders_user FOREIGN KEY (user_id) 
        REFERENCES users(id) ON DELETE CASCADE
);

-- Tabela de ligação orders-products
CREATE TABLE order_items (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_id BIGINT NOT NULL,
    product_id BIGINT NOT NULL,
    quantity INT NOT NULL,
    unit_price DECIMAL(10, 2) NOT NULL,
    
    CONSTRAINT fk_order_items_order FOREIGN KEY (order_id) 
        REFERENCES orders(id) ON DELETE CASCADE,
    CONSTRAINT fk_order_items_product FOREIGN KEY (product_id) 
        REFERENCES products(id)
);

3.4 V5 - Índices para Performance

-- V5__add_indexes.sql
-- Adição de índices para melhorar a performance

-- Índice na data do pedido
CREATE INDEX idx_orders_date ON orders(order_date);

-- Índice no status
CREATE INDEX idx_orders_status ON orders(status);

-- Índice no usuário
CREATE INDEX idx_orders_user ON orders(user_id);

-- Índice na categoria do produto
CREATE INDEX idx_products_category ON products(category);

-- Índice em produtos ativos
CREATE INDEX idx_products_active ON products(active) WHERE active = TRUE;

3.5 V6 - Dados de Referência

-- V6__insert_reference_data.sql
-- Inserção de dados de referência

-- Usuário admin
INSERT INTO users (username, password, email, first_name, last_name) 
VALUES ('admin', '$2a$10$hashedpassword', 'admin@example.com', 'Admin', 'System');

-- Categorias de produtos (via produtos de demo)
INSERT INTO products (name, description, price, stock_quantity, category) VALUES
('Laptop Pro', 'Notebook de alta performance', 1299.99, 50, 'ELECTRONICS'),
('Smartphone X', 'Celular de última geração', 899.99, 100, 'ELECTRONICS'),
('T-Shirt Basic', 'Camiseta 100% algodão', 19.99, 500, 'CLOTHING'),
('Jeans Classic', 'Jeans corte reto', 49.99, 200, 'CLOTHING'),
('Livro Java', 'Guia completo Java', 39.99, 75, 'BOOKS');

---

Parte 4: Migrações Repetíveis

4.1 Criar uma View

Migrações repetíveis são reexecutadas se o arquivo for alterado.

-- R__create_views.sql
-- View de produtos ativos com estoque

CREATE OR REPLACE VIEW v_available_products AS
SELECT 
    id,
    name,
    price,
    stock_quantity,
    category
FROM products
WHERE active = TRUE 
  AND stock_quantity > 0;

-- View de estatísticas por categoria
CREATE OR REPLACE VIEW v_category_stats AS
SELECT 
    category,
    COUNT(*) as product_count,
    AVG(price) as avg_price,
    SUM(stock_quantity) as total_stock
FROM products
WHERE active = TRUE
GROUP BY category;

4.2 Testar

Modifique a view e reinicie:

-- Modifique R__create_views.sql
CREATE OR REPLACE VIEW v_available_products AS
SELECT 
    id,
    name,
    price,
    stock_quantity,
    category,
    'IN_STOCK' as availability  -- Nova coluna!
FROM products
WHERE active = TRUE 
  AND stock_quantity > 0;

Ao reiniciar, o Flyway detecta a mudança do checksum e reexecuta o script.

---

Parte 5: Verificação e Comandos

5.1 Verificar o Estado das Migrações

Abra o console H2 e execute:

-- Histórico completo das migrações
SELECT 
    installed_rank,
    version,
    description,
    type,
    installed_on,
    execution_time,
    success
FROM flyway_schema_history
ORDER BY installed_rank;

Resultado esperado:

installed_rank	version	description	type	success
1	1	create users table	SQL	true
2	2	add email to users	SQL	true
3	3	create products table	SQL	true
4	4	create orders table	SQL	true
5	5	add indexes	SQL	true
6	6	insert reference data	SQL	true
7	NULL	create views	SQL	true

5.2 Comandos Maven (Opcional)

Adicione o plugin Flyway no pom.xml:

<plugin>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-maven-plugin</artifactId>
    <configuration>
        <url>jdbc:h2:file:./target/flywaydb</url>
        <user>sa</user>
        <password></password>
    </configuration>
</plugin>

# Ver o estado
mvn flyway:info

# Aplicar as migrações
mvn flyway:migrate

# Validar
mvn flyway:validate

---

Parte 6: Gestão de Erros

6.1 Simular um Erro

Crie um script com erro:

-- V7__broken_migration.sql
-- Script com erro de sintaxe

CREATE TABLE broken_table (
    id BIGINT PRIMARY KEY
    name VARCHAR(50)  -- Vírgula faltando!
);

Reinicie a aplicação → Erro!

6.2 Corrigir

1. Opção A: Corrija o script e use repair (apenas para dev)

# Marcar como resolvido
mvn flyway:repair

# Reaplicar
mvn flyway:migrate

2. Opção B: Remover o arquivo V7 e a linha na flyway_schema_history

3. Opção C (Produção): Criar V8 para corrigir

-- V8__fix_broken_table.sql
-- Correção do erro V7

DROP TABLE IF EXISTS broken_table;

CREATE TABLE broken_table (
    id BIGINT PRIMARY KEY,
    name VARCHAR(50)
);

6.3 Regra de Ouro

perigo

NUNCA modifique um script de migração já executado em produção!

Sempre crie um NOVO script para corrigir problemas.

---

Parte 7: Migração PostgreSQL

7.1 Configuração Produção

# application-prod.properties
spring.datasource.url=jdbc:postgresql://localhost:5432/flywaydb
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.username=postgres
spring.datasource.password=secret

spring.h2.console.enabled=false

spring.jpa.hibernate.ddl-auto=validate
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

# Flyway
spring.flyway.enabled=true
spring.flyway.clean-disabled=true

7.2 Adaptar os Scripts (se necessário)

Algumas sintaxes diferem entre H2 e PostgreSQL:

-- H2
CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    ...
);

-- PostgreSQL
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    ...
);

Solução: Use scripts específicos por ambiente:

db/migration/
├── h2/
│   └── V1__create_tables.sql
└── postgresql/
    └── V1__create_tables.sql

# application-dev.properties
spring.flyway.locations=classpath:db/migration/h2

# application-prod.properties
spring.flyway.locations=classpath:db/migration/postgresql

---

Parte 8: Endpoint de Verificação

8.1 Controller para Verificar as Migrações

// src/main/java/com/example/flywaydemo/controller/MigrationController.java
package com.example.flywaydemo.controller;

import org.flywaydb.core.Flyway;
import org.flywaydb.core.api.MigrationInfo;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

@RestController
@RequestMapping("/api/migrations")
public class MigrationController {

    @Autowired
    private Flyway flyway;

    @GetMapping
    public List<Map<String, Object>> getMigrations() {
        return Arrays.stream(flyway.info().all())
            .map(this::toMap)
            .collect(Collectors.toList());
    }

    @GetMapping("/pending")
    public List<Map<String, Object>> getPendingMigrations() {
        return Arrays.stream(flyway.info().pending())
            .map(this::toMap)
            .collect(Collectors.toList());
    }

    private Map<String, Object> toMap(MigrationInfo info) {
        return Map.of(
            "version", info.getVersion() != null ? info.getVersion().toString() : "N/A",
            "description", info.getDescription(),
            "type", info.getType().name(),
            "state", info.getState().name(),
            "installedOn", info.getInstalledOn() != null ? info.getInstalledOn().toString() : "N/A"
        );
    }
}

Teste:

curl http://localhost:8080/api/migrations

---

Resumo

Arquivos Criados

Arquivo	Descrição
V1__create_users_table.sql	Tabela users básica
V2__add_email_to_users.sql	Adição da coluna email
V3__create_products_table.sql	Tabela products
V4__create_orders_table.sql	Tabelas orders e order_items
V5__add_indexes.sql	Índices de performance
V6__insert_reference_data.sql	Dados iniciais
R__create_views.sql	Views (repetível)

Comandos Principais

Comando	Ação
mvn flyway:info	Ver o estado das migrações
mvn flyway:migrate	Aplicar as migrações
mvn flyway:validate	Validar a consistência
mvn flyway:repair	Reparar o histórico
mvn flyway:clean	Limpar o banco de dados (PERIGOSO!)

O Que Você Aprendeu

1. ✅ Configurar o Flyway com Spring Boot
2. ✅ Nomear corretamente os scripts (V1__, V2__, R__)
3. ✅ Criar migrações incrementais
4. ✅ Gerenciar dados de referência
5. ✅ Utilizar migrações repetíveis para views
6. ✅ Corrigir erros de migração

---

🎯 Módulo Concluído!

Parabéns! Você concluiu o Módulo 7 sobre bancos de dados e transações.

Resumo do módulo:

• Capítulo 1: Configuração de Datasources (HikariCP)
• Capítulo 2: Gestão de Transações (@Transactional)
• Capítulo 3: Migração com Flyway
• Capítulo 4: Migração com Liquibase
• TP1: Configuração de Datasource
• TP2: Transações e Rollback
• TP3: Migração Flyway (este TP)

➡️ Voltar ao Módulo 7

---

⬅️ Voltar ao Plano de Curso