Pular para conteúdo

Atualização do Banco de Dados em UAT/Homologação

Visão Geral

Este documento descreve o procedimento para atualizar o banco de dados em ambiente de UAT (User Acceptance Testing) ou Homologação quando há divergência entre o histórico de migrations do Entity Framework e o estado real do banco de dados.

Problema

Quando tentamos aplicar migrations em um banco de dados que já possui algumas alterações aplicadas manualmente ou através de outras fontes, o Entity Framework tenta executar todas as migrations novamente, causando erros como:

42P07: relation "NomeTabela" already exists

Isso ocorre porque o banco de dados não possui o histórico completo das migrations na tabela __EFMigrationsHistory, mesmo que as alterações já tenham sido aplicadas.

Solução: Sincronizar o Histórico de Migrations

A solução consiste em marcar manualmente as migrations que já foram aplicadas no banco de dados, inserindo seus registros na tabela __EFMigrationsHistory.

Procedimento Passo a Passo

Pré-requisitos

  • Acesso ao banco de dados via psql ou pgAdmin
  • Lista das migrations que já foram aplicadas no banco
  • Credenciais de acesso ao banco de homologação

Passo 1: Conectar ao Banco de Dados

Usando Make (Recomendado)

# Certifique-se de que seu .env está configurado para homologação
make db-connect

Usando psql Diretamente

PGPASSWORD=<senha> psql -h <host> -p <port> -U <user> -d <database>

Exemplo para ambiente local: 

PGPASSWORD=admin psql -h localhost -p 5432 -U postgres -d NelmetaisDBHomologacao

Exemplo para ambiente de homologação: 

# Use as credenciais do arquivo .env
source .env
PGPASSWORD=$SGE_DB_PASSWORD psql \
  -h $SGE_DB_HOST \
  -p $SGE_DB_PORT \
  -U $SGE_DB_USER \
  -d $SGE_DB_SCHEMA

Passo 2: Verificar o Estado Atual do Histórico

Dentro do psql, execute:

SELECT "MigrationId", "ProductVersion"
FROM "__EFMigrationsHistory"
ORDER BY "MigrationId";

O que você verá: - Lista das migrations já registradas no histórico - Se estiver vazio ou incompleto, precisamos adicionar as migrations faltantes

Passo 3: Identificar as Migrations Faltantes

Compare a lista do banco com as migrations no código fonte:

# Em outro terminal, listar todas as migrations do projeto
make migration-list

# Ou manualmente
ls -la src/Nelmetais.SGE.Data/Migrations/

Exemplo de migrations conhecidas:

  1. 20250111135936_initialcreate
  2. 20250111143052_documento-fiscal-comissao
  3. 20250111164642_documento-fiscal-comissao-planocomissaovenda
  4. 20250121125526_NM2-Documento-Fiscal-Terceiros1
  5. 20250121222434_NM2-Documento-Fiscal-Terceiros2
  6. 20250123204156_NM-vendedor-delegado

Passo 4: Inserir as Migrations Faltantes no Histórico

⚠️ IMPORTANTE: Só insira migrations que você tem CERTEZA que já foram aplicadas no banco!

Ainda dentro do psql, execute:

INSERT INTO "__EFMigrationsHistory" ("MigrationId", "ProductVersion") VALUES
  ('20250111135936_initialcreate', '6.0.18'),
  ('20250111143052_documento-fiscal-comissao', '6.0.18'),
  ('20250111164642_documento-fiscal-comissao-planocomissaovenda', '6.0.18'),
  ('20250121125526_NM2-Documento-Fiscal-Terceiros1', '6.0.18'),
  ('20250121222434_NM2-Documento-Fiscal-Terceiros2', '6.0.18'),
  ('20250123204156_NM-vendedor-delegado', '6.0.18')
ON CONFLICT DO NOTHING;

O ON CONFLICT DO NOTHING evita erros se alguma migration já estiver registrada.

Passo 5: Verificar a Inserção

SELECT "MigrationId", "ProductVersion"
FROM "__EFMigrationsHistory"
ORDER BY "MigrationId";

Resultado esperado: - Todas as 6 (ou mais) migrations devem estar listadas - Ordenadas cronologicamente pelo timestamp no início do nome

Passo 6: Sair do psql

\q

Passo 7: Aplicar as Migrations Pendentes

Agora que o histórico está sincronizado, você pode aplicar as migrations pendentes normalmente:

Usando Make (Recomendado)

# Certifique-se de que seu .env está configurado para homologação
make migrate

Usando dotnet-ef Diretamente

# Com variáveis de ambiente de homologação (use valores do .env)
source .env
make migrate

Verificação Pós-Atualização

1. Verificar Migrations Aplicadas

make migration-list

Ou diretamente no banco:

SELECT * FROM "__EFMigrationsHistory" ORDER BY "MigrationId";

2. Testar a Aplicação

# Rodar a aplicação apontando para homologação
make run-dev

Acesse: http://localhost:8000

3. Verificar Logs

Verifique se não há erros relacionados ao banco de dados nos logs da aplicação.

Backup e Segurança

⚠️ SEMPRE faça backup antes de qualquer alteração!

Backup Rápido

# Com .env configurado para homologação
make db-backup

Backup Compactado (economiza espaço)

make db-backup-compressed

Restaurar Backup (se algo der errado)

# Restaurar último backup
make db-restore

# Ou restaurar arquivo específico
make db-restore-file FILE=./backups/nelmetais-backup-20250127_143000.sql

Troubleshooting

Erro: "relation already exists"

Causa: A migration está tentando criar uma tabela que já existe.

Solução: Marque essa migration como aplicada no histórico (Passo 4).

Erro: "column does not exist"

Causa: Uma migration anterior não foi aplicada corretamente.

Solução: 1. Restaure um backup 2. Aplique as migrations na ordem correta 3. Ou adicione manualmente a coluna faltante

Erro: "password authentication failed"

Causa: Credenciais incorretas no .env.

Solução: Verifique e corrija as variáveis no arquivo .env:

SGE_DB_HOST=<host_do_servidor>
SGE_DB_PORT=<porta>
SGE_DB_SCHEMA=NelmetaisDBHomologacao
SGE_DB_USER=<usuario>
SGE_DB_PASSWORD='<senha>'

⚠️ Nota: As credenciais reais estão no arquivo .env (não versionado). Consulte a equipe de infraestrutura se não tiver acesso.

Checklist Completo

Use este checklist ao atualizar o banco UAT:

  • [ ] 1. Fazer backup do banco de dados (make db-backup)
  • [ ] 2. Conectar ao banco (make db-connect)
  • [ ] 3. Verificar histórico atual (SELECT * FROM "__EFMigrationsHistory")
  • [ ] 4. Identificar migrations faltantes (make migration-list)
  • [ ] 5. Inserir migrations no histórico (SQL INSERT)
  • [ ] 6. Verificar inserção (SELECT novamente)
  • [ ] 7. Sair do psql (\q)
  • [ ] 8. Aplicar migrations pendentes (make migrate)
  • [ ] 9. Verificar se aplicou corretamente (make migration-list)
  • [ ] 10. Testar a aplicação (make run-dev)
  • [ ] 11. Verificar logs por erros
  • [ ] 12. Validar funcionalidades críticas

Ambientes

Desenvolvimento Local

SGE_DB_HOST=localhost
SGE_DB_PORT=5432
SGE_DB_SCHEMA=NelmetaisDBHomologacao
SGE_DB_USER=postgres
SGE_DB_PASSWORD=admin

UAT/Homologação (Servidor)

# ⚠️ Valores sensíveis não devem ser commitados
# Use o arquivo .env local (não versionado)
SGE_DB_HOST=<host_homologacao>
SGE_DB_PORT=<porta>
SGE_DB_SCHEMA=NelmetaisDBHomologacao
SGE_DB_USER=<usuario>
SGE_DB_PASSWORD='<senha>'

Nota: As credenciais reais de homologação estão disponíveis: - No arquivo .env do servidor de homologação - Com a equipe de infraestrutura/DevOps - No gerenciador de senhas da empresa

Produção

# ⚠️ NUNCA aplique migrations diretamente em produção!
# Use sempre scripts SQL gerados e revisados.
make migration-script

Referências

Histórico de Alterações

Data Autor Descrição
2025-01-27 Claude Documentação inicial completa

Notas Importantes

  1. SEMPRE faça backup antes de modificar o banco de dados
  2. Teste em ambiente de teste primeiro (se disponível)
  3. Nunca aplique migrations diretamente em produção - use scripts SQL revisados
  4. Documente todas as alterações feitas manualmente no banco
  5. Comunique a equipe antes de atualizar UAT/Homologação