# Database

> Cria, audita e padroniza dbscripts Sankhya (`dbscripts/V<NNN>-*.xml`) com migrations dual MSSQL/Oracle. Cobre convenções de nomenclatura, mapeamento de tipos (`NUMBER`/`NUMERIC`/`INT`/`FLOAT`/`DECIMAL`/`VARCHAR`/`VARCHAR2`/`CHAR`/`DATE`/`DATETIME`/`TIMESTAMP`), estrutura `<sql>`/`<mssql>`/`<oracle>` e atributos `executar`/`tipoObjeto`/`nomeObjeto`. Use ao adicionar, alterar, revisar, padronizar o…

- **Type:** Skill
- **Install:** `agentstack add skill-snk-devcenter-addon-studio-database`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [snk-devcenter](https://agentstack.voostack.com/s/snk-devcenter)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [snk-devcenter](https://github.com/snk-devcenter)
- **Source:** https://github.com/snk-devcenter/addon-studio/tree/main/plugins/addon-studio/skills/database

## Install

```sh
agentstack add skill-snk-devcenter-addon-studio-database
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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                                           | `CREATE_TABLE`, `ALTER_TABLE`, `INSERT_DATA` |
| ``   | Nome tabela afetada                                                 | `TDCXYZCAD`, `TGFCAB`                        |

---

### Formato XML Base

```xml

    
        
            
        
        
            
        
    

```

### Tags de Banco de Dados

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

```xml

    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`."
3. **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'))` |

```sql
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"`.

```xml

    
        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

```xml

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

```xml

    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

```xml

    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

```xml

    CREATE TABLE TGFCAB (...)

    

ALTER TABLE TGFCAB ADD (XYZ_CODRECEITA VARCHAR2(100))

```

### 5. ALTER TABLE para coluna nativa em tabela nativa

```xml

    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](https://github.com/snk-devcenter)
- **Source:** [snk-devcenter/addon-studio](https://github.com/snk-devcenter/addon-studio)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-snk-devcenter-addon-studio-database
- Seller: https://agentstack.voostack.com/s/snk-devcenter
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.