📜 Schema de Banco de Dados (DBScripts)

O Add-on Studio permite a execução de scripts de banco de dados diretamente através do add-on, uma funcionalidade poderosa para criar ou modificar a estrutura de dados do seu cliente. Com os dbscripts, você pode criar tabelas, views, colunas e outros objetos de banco de forma versionada e segura.

Esta documentação detalha como criar, organizar e gerenciar seus scripts, garantindo que o armazenamento e o acesso aos dados estejam alinhados com as melhores práticas da plataforma.

📂 Estrutura e Organização dos Arquivos

Para que o Add-on Studio reconheça e execute seus scripts, eles devem ser criados dentro do diretório dbscripts no seu projeto.

Versionamento e Nomenclatura

A nomenclatura dos arquivos é crucial para garantir a ordem de execução correta. O padrão é o seguinte:

• O nome do arquivo deve começar com a letra V (de "versão"), seguida por um número que indica a sequência de execução.
• A extensão do arquivo deve ser .xml.

Exemplos: V1.xml, V2.xml, V3.xml, e assim por diante.

✅

Dica: Seguir essa nomenclatura de versionamento é fundamental para a atomicidade dos scripts e para minimizar o risco de erros durante o deploy.

Organizando Scripts em Subpastas

Para projetos com muitos scripts, você pode organizá-los em subpastas dentro de dbscripts. Isso melhora a manutenção e a clareza do seu projeto.

Exemplo de Estrutura:

dbscripts/
    ├── V1_tabelas.xml
    ├── V2_colunas.xml
    └── views/
        ├── V3_vw_projetos.xml
        └── V4_vw_tarefas.xml

O sistema irá percorrer as subpastas e executar os scripts respeitando a numeração do prefixo V.

📝 Estrutura do Arquivo XML

Cada arquivo .xml contém um ou mais scripts a serem executados. A estrutura segue o schema scripts.xsd, que pode ser referenciado para validação na sua IDE.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<scripts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="../.gradle/scripts.xsd">

    <sql nomeTabela="SGT_PROJETOS" ordem="1" executar="SE_NAO_EXISTIR" tipoObjeto="TABLE" nomeObjeto="SGT_PROJETOS" descricao="Cria a tabela de projetos.">
        <mssql>
            CREATE TABLE SGT_PROJETOS (
                ID INT IDENTITY(1,1) PRIMARY KEY,
                NOME VARCHAR(100) NOT NULL,
                DATA_INICIO DATE
            )
        </mssql>
        <oracle>
            CREATE TABLE SGT_PROJETOS (
                ID NUMBER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
                NOME VARCHAR2(100) NOT NULL,
                DATA_INICIO DATE
            )
        </oracle>
    </sql>
</scripts>

Atributos da Tag <sql>

A tag <sql> é o coração do dbscript. Seus atributos controlam como e quando o script será executado.

👍

Dica!

Na sua IDE, posicione o cursor sobre qualquer atributo ou tag para ver a documentação completa diretamente do arquivo xsd.

Scripts para Múltiplos Bancos

Utilize as tags <mssql> e <oracle> para fornecer o código SQL específico para cada banco de dados. Se o seu add-on suporta apenas um tipo de banco, inclua apenas a tag correspondente.

✨ Boas Práticas

Ao trabalhar com dbscripts, seguir estas diretrizes garantirá que seu add-on seja robusto, seguro e de fácil manutenção.

✅ Use Prefixos Únicos
Sempre utilize um prefixo exclusivo para suas tabelas, views e outros objetos (ex: SGT_, MEUADDON_). Isso evita conflitos com tabelas nativas do Sankhya ou de outros add-ons e deixa claro quais objetos pertencem à sua aplicação.

✅ Versionamento Imutável
Trate seus scripts como migrações imutáveis. Uma vez que um script de versão (ex: V1.xml) é aplicado em um ambiente, ele não deve ser alterado. Para realizar novas modificações na estrutura do banco, crie um novo arquivo de versão (ex: V2.xml, V3.xml). Isso garante a previsibilidade e a segurança das atualizações.

✅ Organize em Subpastas
Para projetos complexos, organize seus scripts em subpastas dentro de resources/dbscripts. Isso melhora a legibilidade e a manutenção.

dbscripts/
├── tabelas/
│   ├── V1_tabela_projetos.xml
│   └── V2_tabela_tarefas.xml
└── views/
    └── V3_view_relatorio.xml

✅ Testes Rigorosos
Antes de publicar, teste exaustivamente seus scripts em um ambiente de desenvolvimento que espelhe o ambiente de produção. Verifique se as migrações ocorrem sem erros e se não há efeitos colaterais inesperados.

✅ Compatibilidade de Banco de Dados
Se o seu add-on precisa ser compatível com múltiplos bancos de dados (Oracle e SQL Server), sempre forneça o código SQL específico para cada um dentro das tags <oracle> e <mssql>.

✅ Mantenha a Simplicidade
Crie scripts pequenos e focados em uma única tarefa (ex: um script para criar uma tabela, outro para adicionar uma coluna). Isso facilita a depuração e o gerenciamento.

🚫 Antipadrões (O que Evitar)

Evitar práticas inadequadas é tão importante quanto seguir as boas. Aqui estão os principais antipadrões a serem evitados:

❌ Modificar Tabelas Nativas Diretamente
Nunca, em nenhuma circunstância, adicione, modifique ou remova colunas de tabelas nativas do sistema Sankhya (ex:TGFPRO, TGFCAB, TSIUSU).

• Por quê?

  • Perda de Dados: Suas alterações podem ser sobrescritas ou removidas sem aviso durante uma atualização do sistema Sankhya.
  • Instabilidade: Pode causar comportamento inesperado em funcionalidades padrão do ERP.
  • Perda de Suporte: Modificações diretas em tabelas nativas invalidam o suporte técnico da Sankhya para problemas relacionados.

• Qual a solução correta?
  Se você precisa armazenar informações adicionais relacionadas a uma entidade nativa (como um produto ou um parceiro), crie uma tabela auxiliar com seu prefixo exclusivo. Relacione-a com a tabela nativa usando uma chave estrangeira.

  Exemplo: Para adicionar um campo de "SELO DE GARANTIA" ao produto:

  1. Crie uma tabela SGT_INFOPRODUTO com as colunas CODPROD (chave estrangeira para TGFPRO.CODPROD) e SELOGARANTIA.
  2. Use essa tabela para armazenar seus dados.

❌ Usar o Prefixo GenéricoAD_
Este prefixo significa "Add-on" e é muito genérico. Se múltiplos desenvolvedores o utilizarem, haverá conflitos de nomes de tabelas. Crie um prefixo que identifique unicamente seu projeto ou empresa.

❌ Scripts Desordenados
Tentar criar uma VIEW que consulta uma tabela que ainda não existe irá falhar. Garanta que o atributo ordem e a numeração dos seus arquivos (V1, V2, etc.) sigam uma sequência lógica de dependências.

❌ Remover Ponto e Vírgula (;)
Evite usar ponto e vírgula no final de suas declarações SQL. A plataforma que processa os dbscripts pode interpretar isso de forma incorreta e causar falhas no deploy.

🚀 Deploy e Verificação

Após criar seus arquivos de script, execute o comando de deploy:

./gradlew clean deployAddon

Durante a execução, o log no terminal e no servidor Sankhya exibirá mensagens indicando o sucesso ou a falha de cada script executado, como na imagem abaixo:

Isso identifica que seus scripts foram processados sem nenhum erro. Acesse o banco de dados e confirme que seus objetos foram criados conforme o esperado.