Database

Scripts de Banco de Dados (Addon Studio 2.0)

Instruções para criar/manter scripts migração em dbscripts/ para projetos Addon Studio 2.0.

---

Estrutura dos Scripts

Cada arquivo migração = XML versionamento sequencial estilo Flyway:

dbscripts/
|-- V001-CREATE_TABLE_TDCXYZCAD.xml
|-- V002-CREATE_TABLE_TDCXYZFAT.xml
|-- V003-ALTER_TABLE_TGFCAB.xml
|-- V004-ALTER_TABLE_TDCXYZCAD.xml
|-- V005-INSERT_DATA_TDCXYZCTL.xml
|-- V-_.xml

> Sistema suporta subdiretórios em dbscripts/, percorre respeitando prefixos numéricos.

Convenção de Nomenclatura dos Arquivos

Padrão: V-_.xml

| Componente | Descrição | Exemplos | |:-------------|:--------------------------------------------------------------------|:---------------------------------------------| | V | Versão sequencial 3 dígitos (zero-padded), nunca reutilizar | V001, V002, V003 | | ` | Operação principal script | CREATETABLE, ALTERTABLE, INSERT_DATA | | | Nome tabela afetada | TDCXYZCAD, TGFCAB` |

---

Formato XML Base

Tags de Banco de Dados

Cada ` **deve** conter **ambas** tags e `, SQL equivalente cada banco:

    CREATE TABLE EXEMPLO (CODEXEMPLO INT NOT NULL, CONSTRAINT PK_EXEMPLO PRIMARY KEY (CODEXEMPLO))

CREATE TABLE EXEMPLO (CODEXEMPLO NUMBER(10) NOT NULL, CONSTRAINT PK_EXEMPLO PRIMARY KEY (CODEXEMPLO))

> Regra: Todo ` tem duas tags — primeiro, depois. Nunca omitir. > > **Nota sobre o schema:** o scripts.xsd define / como xs:all` (qualquer ordem, no máximo 1 cada, podendo ter só um dos dois). A regra acima é convenção do projeto para garantir portabilidade dual MSSQL/Oracle — não restrição do schema.

Atributos do Elemento ``

| Atributo | Obrigatório | Descrição | Valores | |:-------------|:------------|:-------------------------------------------------------------------|:----------------------------------------------| | nomeTabela | Sim | Tabela afetada (usado em logs) | Nome tabela | | ordem | Sim | Ordem execução no arquivo. Não duplicar dentro mesmo XML | Inteiro sequencial (1, 2, 3...) | | executar | Sim | Condição execução | SE_NAO_EXISTIR, SE_EXISTIR, SEMPRE | | tipoObjeto | Sim | Tipo objeto verificado por executar | TABLE, COLUMN, FUNCTION, PROCEDURE, TRIGGER, VIEW, CONSTRAINT, PRIMARY KEY, FOREIGN KEY, INDEX | | nomeObjeto | Sim | Nome objeto verificado (identificador único versionamento) | Nome objeto no banco | | descricao | Não | Descrição textual script (documentação) | Texto livre |

Valores de executar — Detalhamento

| Valor | Comportamento | Quando usar | |:-----------------|:---------------------------------------------------------------------------|:------------------------------------------------------------------------| | SE_NAO_EXISTIR | Executa se objeto (tipoObjeto + nomeObjeto) não existir banco | CREATE TABLE, ADD COLUMN — padrão criação objetos novos | | SE_EXISTIR | Executa se objeto já existir banco | ALTER TABLE modificar coluna existente, DROP, migração dados | | SEMPRE | Executa toda vez deploy, independente existência | INSERT/UPDATE dados config, scripts idempotentes. Usar com cautela |

---

Regras de Nomenclatura

Nome de Tabela — Convencao parametrizada por projeto

Padrao obrigatorio: `` — tudo MAIUSCULO, sem underscores.

Componentes:

• `: prefixo fixo do projeto, **3-4 caracteres** UPPER (ex.: TDC, APP, CST`)
• `: sigla do modulo, **3 caracteres** (ex.: FIN, FAT, CFG, CAD`)
• `: sigla curta do contexto/entidade da tabela (ex.: CAB, ITE, CFG, LOG`)

Descobrir convencao do projeto (obrigatorio antes de criar)

1. Inspecionar projeto: procurar tabelas existentes em dbscripts/*.xml (CREATE TABLE), datadictionary/*.xml (`), entities @JapeEntity(table = "..."). Se houver padrao consistente (todas com mesmo prefixo), reusar `.
2. Se projeto novo / sem padrao: perguntar ao dev:

• "Qual prefixo (`, 3-4 chars UPPER) usar para tabelas custom? Ex.: TDC, APP, CST`."
• "Qual sigla 3 chars (`) representa este modulo? Ex.: FIN, FAT`."
• "Qual contexto/entidade (`)? Ex.: CAB, ITE, CFG`."

1. Confirmar nome final antes de gerar artefatos.

Exemplos ilustrativos (`=TDC, =XYZ`):

| Conceito | PRX | MOD3 | CTX | Resultado | |:---------------|:-------|:-------|:---------|:-------------| | Cadastro | TDC | XYZ | CAD | TDCXYZCAD | | Faturamento | TDC | XYZ | FAT | TDCXYZFAT | | Configuracao | TDC | XYZ | CFG | TDCXYZCFG | | Cabecalho nota | TDC | XYZ | CAB | TDCXYZCAB | | Item nota | TDC | XYZ | ITE | TDCXYZITE |

> NOTA: exemplos abaixo usam TDC como prefixo ilustrativo. Substituir pelo `` real do projeto.

Nome de Constraint

| Tipo | Padrao | Exemplo | |:------|:---------------------------|:----------------------------------------------| | PK | PK_ | CONSTRAINT PK_TDCXYZCAD PRIMARY KEY (CODCAD) | | CHECK | CK__ | CONSTRAINT CK_TDCXYZCAD_ATIVO CHECK (ATIVO IN ('S', 'N')) |

CONSTRAINT PK_TDCXYZCAD PRIMARY KEY (CODCAD)
CONSTRAINT PK_TDCXYZFAT PRIMARY KEY (CODPARC, DTFAT)

> Oracle limita identificadores a 30 caracteres (ate 12.1). CK__ com nomes longos estoura — encurtar o sufixo e confirmar com o dev, nunca truncar em silencio.

Nome de Campos

Padrao: MAIUSCULO, sem underscores (excecoes compostos).

Abreviacoes padrao ecossistema Sankhya:

| Prefixo | Significado | Exemplo | |:-------------|:------------------------------------|:----------------------------------------| | COD | Codigo (identificador) | CODPARC, CODUSU | | DT | Data (sem hora) | DTFAT, DTINC | | DH | Data/Hora (com timestamp) | DHINC, DHREC, DHALTER, DHCREATE | | VLR | Valor monetario | VLRMRR, VLRTOTAL | | QTD | Quantidade | QTDTOTAL, QTDEXC | | PERC | Percentual | PERCMRR | | DESCR | Descricao (texto livre) | DESCRERRO, DESCRPRODUTO | | NU | Numero unico movimentos/documentos | NUNOTA, NUIMP, NUPED | | _ | Coluna customizada em tabela nativa | XYZ_CODRECEITA, XYZ_STATUS |

> Colunas customizadas em tabelas nativas Sankhya (ex: TGFCAB) usam prefixo do modulo do addon + _ (ex: _NOMECAMPO) para evitar conflito com core Sankhya e com outros addons. Nunca usar prefixo generico tipo AD_.

> Chaves primarias sequenciais: nao usar prefixo ID. Para cadastros, usar COD (ex: CODCAD, CODCFG); para movimentos/documentos, usar NU (ex: NUNOTA, NUIMP).

> Quem gera a PK e o dicionario, nao o banco. Toda tabela nova do addon nasce com PK automatica (sequenceType="A" no datadictionary/, ver skill data-dictionary) — inclusive config, log, registro e tabela de apoio. No DDL a coluna PK e NUMBER(10)/INT simples: sem IDENTITY, GENERATED AS IDENTITY, CREATE SEQUENCE ou trigger de sequencia.

---

Tipos de Dados

Mapeamento por Banco

| Tipo lógico | Oracle | SQL Server | Uso | |:------------|:---------------|:----------------|:------------------------------------------| | Inteiro | NUMBER(10) | INT | COD*/NU* sequenciais, contadores, FKs | | Decimal | FLOAT(126) | FLOAT(53) | Valores monetários, percentuais | | Texto | VARCHAR2(n) | VARCHAR(n) | Texto tamanho variável | | Flag S/N | VARCHAR2(1) | CHAR(1) | Flags booleanas | | Data/Hora | DATE | DATETIME | Data e/ou data+hora |

> Decimal é FLOAT, não DECIMAL/NUMBER(18,N). Tabelas nativas Sankhya usam FLOAT nos dois bancos (FLOAT(126) Oracle, FLOAT(53) SQL Server), sem escala na coluna. Casas decimais são do dicionário (nuCasasDecimais), não do DDL. Coluna de addon segue o nativo: mesmo tipo em JOIN/comparação com tabela nativa, e JAPE lê como BigDecimal do mesmo jeito. > > Cuidado: o nome é igual, a precisão não. Oracle FLOAT(126) é subtipo de NUMBER — decimal exato. SQL Server FLOAT(53) é IEEE 754 binário — sujeito a resíduo de arredondamento. Em cálculo financeiro, arredondar no Java com BigDecimal; nunca comparar FLOAT por igualdade exata em SQL.

Diferenças de Sintaxe

| Operação | Oracle | SQL Server | |:-------------------|:----------------------------------|:--------------------------------------| | CREATE TABLE | Igual | Igual (usar tipos SQL Server) | | ALTER TABLE ADD | ALTER TABLE X ADD (COL TYPE) | ALTER TABLE X ADD COL TYPE | | ALTER TABLE MODIFY | ALTER TABLE X MODIFY (COL TYPE) | ALTER TABLE X ALTER COLUMN COL TYPE | | INSERT sem tabela | SELECT 1 FROM DUAL | SELECT 1 |

> Nota: Oracle DATE guarda data+hora. SQL Server usar DATETIME mesmo efeito.

---

Filosofia: CREATE TABLE Mínimo + ALTER TABLE por Coluna

CREATE TABLE contém só colunas PK + constraint. Demais colunas adicionadas individualmente via ALTER TABLE ADD mesmo arquivo XML. Garante:

• Scripts atômicos, fáceis auditar
• Granularidade rollback/diagnóstico
• Padrão único (ALTER TABLE ADD) tabelas novas e tabelas nativas

---

Padrões de Script por Operação

Padrões completos de DDL — CREATE TABLE mínimo (somente PK + constraint), ALTER TABLE para adicionar/modificar colunas (uma por `), CHECK constraints para LISTA/CHECKBOX, tabelas nativas (nativeTable), relação dicionário ↔ scripts e INSERT para dados de configuração — em [references/script-patterns.md`](references/script-patterns.md).

---

Mapeamento Dicionário de Dados -> Tipos de Banco (Referência)

| dataType no dicionário | Oracle | SQL Server | Observação | |:----------------------------------|:------------------------|:------------------------|:-------------------------------------| | INTEIRO | NUMBER(10) | INT | | | TEXTO (com size) | VARCHAR2() | VARCHAR() | | | DECIMAL (com nuCasasDecimais) | FLOAT(126) | FLOAT(53) | Escala não vai na coluna — nuCasasDecimais manda | | DATA_HORA ou DATA | DATE | DATETIME | | | CHECKBOX | VARCHAR2(1) | CHAR(1) | + CHECK IN ('S', 'N') | | LISTA (com `) | VARCHAR2() | VARCHAR() | **+ CHECK IN ()** | | PESQUISA | Depende do targetType | Depende do targetType | Ex: INTEIRO -> NUMBER(10) / INT` |

CHECK Constraints — Domínio Fechado

Campo LISTA (valores das `) e campo CHECKBOX ('S'/'N') geram **CHECK constraint** em próprio, logo após o ALTER TABLE ADD da coluna. Nome: CK__, com tipoObjeto="CONSTRAINT"`.

    
        ALTER TABLE TDCXYZCAD ADD CONSTRAINT CK_TDCXYZCAD_ATIVO CHECK (ATIVO IN ('S', 'N'))
    
    
        ALTER TABLE TDCXYZCAD ADD CONSTRAINT CK_TDCXYZCAD_ATIVO CHECK (ATIVO IN ('S', 'N'))
    

Padrões completos — LISTA, tabela nativa, evolução das opções (DROP + recreate) — em [references/script-patterns.md](references/script-patterns.md).

Mapeamento Banco -> Tipo do Dicionário (inverso)

| Oracle | SQL Server | Tipo Dicionário | Condição | |:---------------|:----------------------------|:---------------------------|:---------------------------| | NUMBER(10) | INT | INTEIRO | Sem FK | | NUMBER(10) | INT | PESQUISA | Com relacionamento (FK) | | FLOAT(126) | FLOAT(53) | DECIMAL | Com casas decimais | | NUMBER(18,N) | DECIMAL(18,N) | DECIMAL | Legado — coluna antiga, ler normal; não usar em coluna nova | | VARCHAR2(n) | VARCHAR(n) | TEXTO size=n | Texto livre, sem CHECK | | VARCHAR2(n) + CHECK IN (...) | VARCHAR(n) + CHECK IN (...) | LISTA + ` | Enum valores definidos | | VARCHAR2(1) + CHECK IN ('S','N') | CHAR(1) + CHECK IN ('S','N') | CHECKBOX | Flag booleana | | DATE | DATETIME (só data) | DATA | Semântica: só data | | DATE | DATETIME (com hora) | DATA_HORA` | Semântica: data + hora |

---

Anti-patterns (PROIBIDO)

1. Omitir uma das tags de banco

CREATE TABLE TABELA (CODCAD NUMBER(10) NOT NULL, CONSTRAINT PK_TABELA PRIMARY KEY (CODCAD))

    

    

CREATE TABLE TABELA (CODCAD INT NOT NULL, CONSTRAINT PK_TABELA PRIMARY KEY (CODCAD))

CREATE TABLE TABELA (CODCAD NUMBER(10) NOT NULL, CONSTRAINT PK_TABELA PRIMARY KEY (CODCAD))

    

2. Ponto-e-vírgula no final do SQL

    CREATE TABLE TABELA (CODCAD NUMBER(10) NOT NULL, CONSTRAINT PK_TABELA PRIMARY KEY (CODCAD));

    

CREATE TABLE TABELA (CODCAD NUMBER(10) NOT NULL, CONSTRAINT PK_TABELA PRIMARY KEY (CODCAD))

> Sistema adiciona terminador automaticamente. Ponto-e-vírgula causa erro execução.

3. CREATE TABLE com todas as colunas

    CREATE TABLE TDCXYZCAD (
    CODCAD NUMBER(10) NOT NULL,
    DESCR VARCHAR2(200),
    CODPARC NUMBER(10),
    ATIVO VARCHAR2(1),
    CONSTRAINT PK_TDCXYZCAD PRIMARY KEY (CODCAD)
    )

    

CREATE TABLE TDCXYZCAD (
CODCAD NUMBER(10) NOT NULL,
CONSTRAINT PK_TDCXYZCAD PRIMARY KEY (CODCAD)
)

    

4. CREATE TABLE para tabela nativa

    CREATE TABLE TGFCAB (...)

    

ALTER TABLE TGFCAB ADD (XYZ_CODRECEITA VARCHAR2(100))

5. ALTER TABLE para coluna nativa em tabela nativa

    ALTER TABLE TGFCAB ADD (CODPARC NUMBER(10))

    

ALTER TABLE TGFCAB ADD (XYZ_CODRECEITA VARCHAR2(100))

6. Modificar estrutura de colunas nativas do Sankhya

NUNCA alterar tabelas ERP core. Pode adicionar colunas com prefixo addon, mas nunca modificar/remover colunas existentes.

7. Usar prefixo genérico AD_

Usar sempre prefixo espec

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: snk-devcenter
• Source: snk-devcenter/addon-studio
• License: MIT

Install and usage instructions live in the source repository linked above.