1  O que é o Tools

O tools é uma ferramenta desenvolvida para criar, atualizar e validar a estrutura do banco de dados da aplicação. Sua execução se dá por linha de comando, ao iniciar o executável de .bat em Windows e .sh em sistemas Linux. 

A execução do tools é essencial sempre que houver troca de versão da aplicação ou necessidade de garantir que o banco esteja compatível com a estrutura esperada.

Cada versão da aplicação possui sua própria versão do Tools, sendo necessário executar a versão do Tools correspondente a versão da aplicação na qual deseja compatibilizar o banco de dados.

2 Estrutura de diretórios

A pasta do tools por padrão fica no diretório de versão do SFA, que se localiza no caminho:  ?:\ws\install\versoes\[ambiente]\[versão]\tools

Os diretórios do tools possuem a seguinte estrutura: 

• lib/: contém os arquivos .jar da versão (verifique o arquivo revision.txt para a versão correspondente);
• logs/: armazena os logs de execução do Tools;
• changescliente.xml: registros padrão para entidades do banco;
• hibernate.properties: configurações de conexão com o banco de dados;
• SIM3GTools.bat / SIM3GTools.sh: executável para iniciar o Tools;

Recomendamos manter a última versão executada do tools dentro do diretório ?:\ws\tools\[ambiente], para facilitar futuras manutenções.

3 Configurações do Tools

Conexão com banco de dados: Para configurar a conexão com o banco de dados do tools, edite o arquivo hibernate.properties. Segue abaixo a estrutura do arquivo de configuração, lembrando que o exemplo abaixo é uma configuração para o PostgreSQL, sendo necessário ajustar o driver e o dialect em caso de utilizar outra SGBD.

Executável do Tools: Pode ser necessário configurar o executável do tools SIM3GTools (.bat ou .sh).

Windows: Valide se o caminho do comando cd está consistente com o diretório do tools e se o endereço do java está correto. Também recomendamos um aumento da quantidade de memória para execução do processo. A memória é definida no parâmetro “-Xmx” por padrão o mesmo vem com 512M configurado, o ideal é aumentar para 3G, deixando o parâmetro como “-Xmx3G”. Segue abaixo a estrutura do executável.

• Linux: Recomendamos um aumento da quantidade de memória para execução do processo. A memória é definida no parâmetro “-Xmx” por padrão o mesmo vem com 512M configurado, o ideal é aumentar para 3G, deixando o parâmetro como “-Xmx3G”. Segue abaixo a estrutura do executável.

4 Opções do Tools

O Tools possui diversas opções de ações diferentes, seguem abaixo todas as opções disponíveis, com orientações sobre o uso e observações importantes.

Opção 1 – Migrar versão do Tools (Depreciada)

Uso: Não executar. Procedimento utilizado apenas em versões muito antigas do SFA. Não é mais suportado e não deve ser utilizado.
Opção 2 – Gerar log SQL das alterações

Uso: Quando não é possível executar o Tools diretamente no banco de dados, por exemplo, por falta de permissões. Gera um arquivo .sql com as alterações necessárias na base, para execução manual posterior por um usuário com permissão.
Opção 3 – Aplicar alterações à base de dados

Uso: Executa automaticamente as alterações listadas no log gerado pela opção 2. Inclui tentativas de exclusão (DROP) de objetos e adição de constraints NOT NULL. Pode gerar erros caso a base já possua dados que impeçam essas alterações.
Opção 4 – Verificar integridade da base

Uso: Valida a estrutura do banco de dados. Ao final, gera um arquivo fix.sql na raiz da pasta do Tools.Esse script deve ser executado manualmente no banco, analisando e corrigindo possíveis erros identificados.
Opção 5 – Atualizar ou adicionar scripts padrão do sistema

Uso: Insere ou atualiza registros essenciais para o funcionamento do SFA. Inclui parâmetros, configurações e dados-base como tabela, tempo, tipocampo, entre outros.

Opção 6 – Migrar versão do Tools sem NOT NULL e sem DROPs (Depreciada)

Uso: Não executar. Procedimento utilizado apenas em versões muito antigas do SFA. Não é mais suportado e não deve ser utilizado.
Opção 7 – Aplicar alterações à base de dados sem NOT NULL e sem DROPs

Uso: Estrutura toda a base conforme a versão da aplicação definida no arquivo hibernate.properties, sem aplicar constraints NOT NULL e sem remover tabelas. Minimiza o risco de perda de dados existentes.

Opção 8 – Gerar log SQL dos scripts padrão

Uso: Similar à opção 2, mas voltada para os scripts padrão do sistema. Gera um arquivo .sql com as alterações necessárias para execução manual, quando não é possível rodar o Tools diretamente no banco.

Opção 9 – Criar backups de tabelas de configuração

Uso: Cria backups das seguintes tabelas, com nome no formato NOMETABELA+DATAHORAATUAL:parametro, regra, perfilacessoregra, perfilacesso.

Opção 10 – Validar e corrigir Sequences e WsVersao

Uso: Corrige problemas em sequences e no campo wsversao que podem impedir inserções na aplicação, especialmente após um restore da base.

Opção 11 – SIM3Gmp – Gerar log SQL das alterações (Depreciada)

Uso: Não utilizar.Criada para o produto Sim3GMP, atualmente descontinuado.

Opção 12 – SIM3Gmp – Aplicar alterações à base de dados (Depreciada)

Uso: Não utilizar. Criada para o produto Sim3GMP, atualmente descontinuado.

Opção 14 – Sair

Uso: Encerra o Tools corretamente. Recomendado sempre após finalizar qualquer operação.

Opção 15 – Verificar integridade da base e aplicar correções

Uso: Combina a verificação de integridade da opção 4 com a execução automática do fix.sql. Equivalente à relação opção 3 em relação à opção 2.
Opção 18 – Atualizar ou adicionar scripts customizados (cliente)

Uso: Atualiza ou insere scripts específicos para versões customizadas da aplicação ou para o módulo pedidoengine.

5 Roteiros de Execuções Recomendados

Seguem abaixo recomendações de roteiro de opções a serem executadas.

Migração de Versão

Recomendado: Opção 3 - Opção 7 - Opção 15 - Opção 5 - Opção 18 - Opção 4

Versões SVN / Git < 8.2.5

Recomendado: Opção 7 > Opção 4 (executar fix.sql manualmente) > Opção 5

Versões Git >= 8.2.5 e < 8.3.9

Recomendado: Opção 7 > Opção 15 > Opção 5

Versões Git >= 8.3.9

Recomendado: Opção 7 > Opção 15 > Opção 5 > Opção 18

6 Como Validar o Log

Para analisar o log de execução, acesse o diretório logs disponível na pasta do tools e então abra o arquivo tools.log. Dentro dele fica o registro completo de toda a execução do tools, sendo possível validar as ações realizadas e erros que podem ter ocorrido durante a execução

7 Erros Comuns do Tools

• Executável não inicia: Se o Tools não estiver iniciando, verifique se o caminho do Java está correto no arquivo executável (SIM3GTools), conforme orientado no tópico 3 (Configurações do Tools). No caso de Windows, também valide se o comando cd está consistente com o diretório do tools.
  
  
• Erro de conexão com banco de dados: Se for exibido erro de conexão com o banco de dados, valide se o arquivo hibernate.properties está configurado de forma consistente, conforme orientamos no tópico 3 (Configurações do Tools). Caso os dados estejam consistentes, mas ainda está obtendo erro, verifique se o banco de dados está ativo e permitindo conexões de outro servidor, no caso da aplicação e banco de dados estarem em servidores diferentes.

8 Considerações e Boas Práticas

Para uma execução segura do Tools, recomendamos que sejam parados os serviços do SFA que acessam o banco de dados (WildFly, Sincronização, Integração) e então seja reiniciado o banco de dados, para garantir que processos persistentes não travem a execução.

Caso deseje realizar o processo com o banco ativo, com o comando abaixo é possível verificar se existem processos persistentes no banco de dados, que podem travar a execução do Tools:

select pid, datname, backend_start, wait_event_type, state, query  
from pg_catalog.pg_stat_activity
where datname = 'nome_do_banco'
order by state;

Para encerrar esses processos, utilize o comando abaixo: 

SELECT pg_terminate_backend(pid);