Schema Migration — essência, tipos e ferramentas de migração de esquemas de BD

O que é Schema Migration

Schema Migration é a prática de gerenciar mudanças na estrutura do banco de dados por meio de arquivos versionados que são aplicados sequencialmente a diferentes ambientes. Cada arquivo contém um conjunto de comandos SQL: criar uma tabela, adicionar uma coluna, modificar um índice ou atualizar restrições. A ferramenta de migração rastreia as versões aplicadas e garante que cada mudança seja executada exatamente uma vez.

Ao contrário de Data Migration, que transfere o conteúdo das tabelas, Schema Migration gerencia apenas a estrutura — operações DDL. Esta é uma distinção fundamental: Schema Migration é executada antes de Data Migration, criando o esquema de destino no qual os dados são então carregados. De acordo com a Redgate (2024), 62% dos incidentes em bancos de dados de produção estão relacionados a mudanças manuais de esquema sem scripts de migração.

Versionamento de migrações

Cada Schema Migration recebe um identificador único — geralmente uma versão (V1, V2) ou um timestamp. A ferramenta armazena uma lista de migrações aplicadas em uma tabela especial (flyway_schema_history, alembic_version). Na inicialização, ela compara a lista com os arquivos no classpath e aplica apenas as novas. Idempotência é uma propriedade chave: reexecutar não causa efeitos colaterais.

Tipos de mudanças de esquema

Operações típicas de Schema Migration: criar tabelas (CREATE TABLE), adicionar colunas (ALTER TABLE ADD COLUMN), alterar tipos, criar índices, adicionar chaves estrangeiras e atualizar sequências. Migrações mais complexas incluem renomear colunas preservando dados, dividir uma tabela em várias e replicar um esquema entre shards.

Por que a migração de esquema de BD é necessária

Sem Schema Migration, os desenvolvedores alteram o banco de dados manualmente — editam DDL no console, adicionam colunas no ambiente dev e as copiam para staging de memória. O resultado: desvio de esquema entre ambientes, perda de mudanças durante a implantação e migrações quebradas em produção. Schema Migration resolve três problemas principais: consistência, reprodutibilidade e auditoria.

Consistência entre ambientes

Quando a estrutura do banco de dados está descrita em código, ela é idêntica em dev, staging e produção. Um desenvolvedor não pode esquecer de aplicar uma mudança — a ferramenta executará todas as migrações perdidas sequencialmente. Se uma coluna estiver faltando em produção, mas o código a exigir, o aplicativo falhará com um erro. A verificação automática elimina esse cenário.

Reprodutibilidade para novos desenvolvedores

Um novo membro da equipe executa flyway migrate e obtém o esquema atual em segundos — sem um dump de produção ou consultas DDL manuais. Isso é especialmente importante em uma arquitetura de microsserviços, onde cada serviço tem seu próprio banco de dados e o esquema é construído a partir de dezenas de migrações. A reprodutibilidade total reduz a integração de dias para minutos.

Auditoria de mudanças

Cada Schema Migration é armazenada no sistema de controle de versão junto com o código do aplicativo. Você pode abrir um Pull Request, ver os comandos SQL exatos da mudança de esquema e realizar uma revisão de código. Em caso de incidente, é fácil determinar qual migração foi aplicada por último e quem a escreveu. O histórico do Git fornece um rastro completo das mudanças no banco de dados ao longo de todo o projeto.

Ferramentas de migração de esquemas

Existem dezenas de ferramentas de Schema Migration para diferentes linguagens e plataformas. A escolha depende da stack de tecnologia, do formato de descrição das migrações e dos requisitos de rollback. Vamos ver as principais categorias e ferramentas populares.

Como escolher uma ferramenta

Para stacks Java/Kotlin — Flyway como o mais leve e previsível. Para projetos com rollbacks frequentes — Liquibase, que tem rollback integrado em sua arquitetura. Para Python/Django — Alembic como ferramenta padrão do SQLAlchemy. Para startups sem engenheiro DevOps — escolha a ferramenta com menos configuração: Flyway requer apenas um arquivo de script e o comando migrate.

Soluções comerciais

Além das ferramentas open-source, existem soluções comerciais: Redgate SQL Change Automation, Datical DB e DBmaestro. Elas fornecem comparação visual de esquemas, resolução automática de conflitos e integração com pipelines CI/CD. No entanto, para a maioria dos projetos, Flyway ou Alembic cobrem 100% das necessidades sem licenças adicionais.

Migração com Flyway

Vamos ver um exemplo prático de Schema Migration em Kotlin com Flyway. Criaremos uma migração que adiciona uma tabela orders a um banco de dados PostgreSQL. Flyway cria automaticamente a tabela flyway_schema_history e rastreia as versões aplicadas.

-- V1__Create_Orders_Table.sql
CREATE TABLE orders (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id         UUID NOT NULL,
    total_amount    DECIMAL(10,2) NOT NULL,
    currency        VARCHAR(3) NOT NULL DEFAULT 'USD',
    status          VARCHAR(20) NOT NULL DEFAULT 'pending',
    created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id)
);

Conexão do Flyway em um projeto Kotlin através da configuração dataSource. Após a configuração, o comando flyway:migrate aplicará todas as novas migrações do classpath.

// FlywayConfig.kt — configuração do Flyway no Spring Boot
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.flywaydb.core.Flyway

@Configuration
class FlywayConfig {
    @Bean
    fun flyway(dataSource: DataSource): Flyway {
        return Flyway.configure()
            .dataSource(dataSource)
            .locations("classpath:db/migration")
            .baselineOnMigrate(true)
            .load()
    }
}

Alembic para projetos Python

Alembic é uma ferramenta de Schema Migration para Python construída sobre SQLAlchemy. Sua principal característica é a autogeração de scripts comparando o modelo SQLAlchemy com o esquema atual do banco de dados. Alembic é adequado para projetos Django, FastAPI e Flask.

Inicialização e criação de uma migração

Após a inicialização (alembic init alembic) e configuração da string de conexão, o comando alembic revision --autogenerate escaneia os modelos SQLAlchemy e gera um script de migração. O desenvolvedor só precisa revisar o código gerado e aplicá-lo via alembic upgrade head. Autogenerate economiza horas de escrita manual de DDL.

# models.py — modelo SQLAlchemy para autogeração
from sqlalchemy import Column, Integer, String, DateTime, Enum
from sqlalchemy.orm import DeclarativeBase
import enum

class OrderStatus(enum.Enum):
    pending = "pending"
    paid = "paid"
    shipped = "shipped"

class Base(DeclarativeBase):
    pass

class Order(Base):
    __tablename__ = "orders"
    id = Column(Integer, primary_key=True)
    status = Column(Enum(OrderStatus), nullable=False)
    created_at = Column(DateTime, nullable=False)

Melhores práticas de migração de esquemas

Equipes experientes desenvolveram um conjunto de regras de Schema Migration que reduzem o risco de falhas e simplificam a depuração. Seguir essas práticas é um sinal de uma cultura de engenharia madura. Cinco regras principais cobrem o design, teste e implantação de migrações.

Uma migração — uma mudança

Cada Schema Migration deve fazer exatamente uma mudança lógica: criar uma tabela, adicionar uma coluna ou modificar um índice. Misturar várias operações em uma migração complica o rollback — se a segunda operação falhar, a primeira já foi aplicada e precisa ser revertida separadamente. Passos pequenos são a base de migrações confiáveis.

Nunca editar migrações publicadas

Depois que uma migração é aplicada à produção, ela não pode ser modificada — apenas uma nova migração que corrija o problema pode ser criada. Editar uma migração publicada quebra o rastreador: desenvolvedores com outro banco de dados verão uma incompatibilidade de hash. Migrações imutáveis garantem comportamento previsível em todos os ambientes.

Teste em uma cópia de produção

Antes de aplicar uma Schema Migration em produção, execute-a em uma cópia dos dados de produção. O objetivo é verificar a velocidade de execução, a presença de bloqueios de tabela e a correção das mudanças. Para tabelas grandes, ALTER TABLE pode bloquear escritas por horas — os testes identificarão isso antecipadamente. Staging com um dump de produção é uma etapa obrigatória.

Evitar NOT NULL para novas colunas

Uma nova coluna sem valor padrão com NOT NULL é uma causa comum de falha de migração. Em registros existentes, o valor será NULL, e NOT NULL causará um erro. Melhor prática: crie a coluna com um valor padrão e nullable, depois adicione NOT NULL em uma migração separada após preencher os dados.