Versionamento banco dados: 9 boas práticas essenciais

Versionar banco de dados significa controlar cada mudança no esquema, nos dados de referência e nos scripts de migração, do mesmo jeito que fazemos com código-fonte. Sem isso, o famoso "funciona na minha máquina" vira um pesadelo quando o schema de produção está diferente do de desenvolvimento. A seguir, 9 boas práticas que separam times que controlam o caos de times que são controlados por ele.

1. Use migrations incrementais e sequenciais

Cada alteração no banco deve ser um script de migração numerado e sequencial (ex.: V001__cria_tabela_usuarios.sql, V002__adiciona_coluna_email.sql). Ferramentas como Flyway e Liquibase aplicam essas migrations na ordem certa e registram o histórico em uma tabela de controle. Isso elimina o risco de pular ou repetir uma mudança.

2. Versionamento junto com o código-fonte

O repositório do banco deve estar no mesmo repositório Git do código da aplicação (ou em um repositório irmão, com versão espelhada). Quando o desenvolvedor faz checkout de uma branch, ele obtém também o esquema de banco correspondente. Isso evita incompatibilidades entre código e schema.

3. Sempre inclua scripts de rollback

Toda migration deve ter um script de reversão (rollback). Se a V003_adiciona_coluna_preco.sql falhar em produção, você precisa de um V003_rollback.sql que desfaça exatamente aquela alteração. Sem rollback, corrigir um erro exige intervenção manual, o que versionamento deveria evitar.

4. Versionar dados de referência (não dados transacionais)

Dados de referência, como tabelas de status, categorias ou configurações, devem ser versionados junto com o esquema. Já dados transacionais (pedidos, usuários) ficam fora do versionamento. Uma boa prática: use seeds ou fixtures para popular tabelas de referência em cada ambiente.

5. Teste as migrations em staging antes de produção

Nunca aplique uma migration diretamente em produção sem antes testá-la em um ambiente de staging que espelhe o schema e o volume de dados reais. Uma migration que funciona com 100 registros pode travar com 100 mil. Ferramentas como Docker ajudam a recriar ambientes idênticos.

6. Documente cada mudança no script

Cada migration deve conter um comentário claro sobre o que a alteração faz e por que é necessária. Exemplo: "-- Adiciona índice na coluna email para acelerar buscas de login". Isso ajuda novos membros do time e facilita auditorias. Documentação não substitui código autoexplicativo, mas reduz dúvidas.

7. Evite alterações manuais diretas no banco

Por mais urgente que pareça, alterar uma tabela diretamente no MySQL Workbench ou SSMS sem passar pelo versionamento quebra o histórico e gera divergência entre ambientes. Se precisar de uma hotfix, crie a migration, teste em staging e aplique via pipeline. A pressa não justifica o caos.

8. Use branches para mudanças complexas

Se uma alteração envolve múltiplas migrations interdependentes (ex.: renomear tabela e atualizar chaves estrangeiras), crie uma branch específica no Git. Isso permite revisar e testar o conjunto completo antes de mesclar na main. O merge da branch deve incluir todas as migrations daquela feature.

9. Automatize a aplicação via pipeline CI/CD

O processo manual de rodar migrations é propenso a erro. Configure sua pipeline (GitHub Actions, GitLab CI, Jenkins) para executar as migrations automaticamente após o deploy da aplicação. Se a migration falhar, a pipeline deve abortar e notificar o time. Isso garante consistência e rastreabilidade.

Como escolher a ferramenta certa?

Para times pequenos ou projetos simples, Flyway é uma escolha direta e leve. Se você precisa de suporte a múltiplos bancos e workflows mais complexos, Liquibase oferece mais flexibilidade. Ambos se integram bem com Git e pipelines CI/CD. O importante não é a ferramenta, mas o processo: versionar sempre, testar antes, documentar cada passo.

Perguntas Frequentes

Qual a diferença entre Flyway e Liquibase?

Flyway é mais simples e baseado em scripts SQL puros. Liquibase permite escrever migrations em XML, YAML ou JSON e oferece rollback mais robusto. Ambos são open source e amplamente adotados.

Devo versionar o banco inteiro ou só o esquema?

Versionar apenas o esquema (tabelas, views, índices) e dados de referência. Dados transacionais (pedidos, usuários) não devem ser versionados, eles vivem no banco, não no repositório.

Como lidar com migrations que demoram muito em produção?

Para tabelas grandes, use técnicas como adicionar colunas com DEFAULT NULL ou criar índices online (se o banco suportar). Teste o tempo de execução em staging com volume similar ao de produção.

É possível versionar bancos NoSQL?

Sim, com adaptações. MongoDB, por exemplo, não tem esquema rígido, mas você pode versionar índices e scripts de migração de dados. Ferramentas como mongodb-migrate ajudam.

O que fazer se uma migration quebrar em produção?

Execute o script de rollback imediatamente. Depois, corrija a migration, teste em staging e reaplique. Nunca tente corrigir manualmente o banco, isso gera divergência e perde o histórico.

Preciso versionar stored procedures e functions?

Sim. Procedures, functions e triggers devem ser versionados como parte do esquema. Crie migrations específicas para cada objeto e evite alterá-los diretamente no banco.