# Versionamento banco dados: 9 boas práticas essenciais > Versionamento de banco de dados exige boas práticas como controle de esquemas, migrations e dados de referência. Nove práticas essenciais incluem versionar migrations incrementalmente, usar ferramentas como Flyway ou Liquibase, manter scripts de rollback, versionar dados de referência, integrar com CI/CD, documentar mudanças, testar migrations em ambientes isolados, evitar alterações manuais diretas e revisar código de banco de dados. *PosUp · Apps e Software · 12 de julho de 2026 · Patrícia Lemos* Versionar banco de dados é tão crítico quanto versionar código. Neste guia, apresentamos 9 boas práticas para controlar esquemas, migrations e dados de referência, garantindo consistência entre ambientes e equipes. 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. --- Fonte (canonical): https://posup.com.br/apps-e-software/versionamento-banco-dados-9-boas-praticas-essenciais/