# DB V2

O conector **DB V2** executa comandos SQL como `SELECT`, `INSERT`, `UPDATE` e `DELETE`, além de poder chamar procedimentos armazenados. Ele processa essas operações e retorna os resultados em um formato JSON estruturado.

Para ver a lista completa de bancos de dados compatíveis com este conector, consulte a nossa [documentação de Bancos de dados suportados](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/supported-databases).

## **Parâmetros**

Configure o conector usando os parâmetros abaixo. Os campos que suportam [expressões Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview) estão marcados na coluna **Suporta DB**.

{% tabs fullWidth="true" %}
{% tab title="General" %}

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Tipo</th><th>Suporta DB</th><th>Padrão</th></tr></thead><tbody><tr><td><strong>Use Dynamic Account</strong></td><td>Se habilitado, a conta é definida dinamicamente durante a execução. Se desabilitado, uma conta estática é selecionada da lista.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Scoped</strong></td><td>Se habilitado, a conta armazenada fica isolada de outros subprocessos. Nesse caso, os subprocessos veem sua própria versão dos dados da conta armazenada. Disponível apenas se o parâmetro <strong>Use Dynamic Account</strong> estiver habilitado.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Account Name</strong></td><td>O nome da conta dinâmica usada pelo conector. Essa conta deve ter sido previamente configurada em um conector <a href="../tools/store-account"><strong>Store Account</strong></a> no pipeline para que este processo tenha efeito. Disponível apenas se o parâmetro <strong>Use Dynamic Account</strong> estiver habilitado.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Account Type</strong></td><td>O tipo de conta a ser usado pelo conector. As opções são: <strong>AWS V4, Basic</strong>, <strong>Kerberos</strong> e <strong>Azure Key</strong>.</td><td>String</td><td>❌</td><td><code>Basic</code></td></tr><tr><td><strong>Account</strong></td><td>As <a href="https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts">credenciais da conta</a> usadas para conectar ao banco de dados.</td><td>Account</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Fail on Error</strong></td><td>Se habilitado, a execução do pipeline é interrompida em caso de erro. Se desabilitado, o pipeline continua e o erro é retornado na mensagem de saída do conector com <code>"success": false</code>.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Operation" %}

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Tipo</th><th>Suporta DB</th><th>Padrão</th></tr></thead><tbody><tr><td><strong>Type</strong></td><td>O tipo de dado da propriedade declarado na instrução SQL.</td><td>String</td><td>❌</td><td><code>Query</code></td></tr><tr><td><strong>Database URL</strong></td><td>A string de conexão JDBC para o banco de dados de destino.</td><td>String</td><td>✅</td><td><code>jdbc:mysql://host:port/database</code></td></tr><tr><td><strong>SQL Statement</strong></td><td>A consulta SQL ou chamada de procedimento a ser executada. Valores dinâmicos podem ser inseridos usando Double Braces.</td><td>String</td><td>✅</td><td><code>SELECT DATE_FORMAT(SYSDATE(), '%Y-%m-%d') as DATA</code></td></tr><tr><td><strong>Batch</strong></td><td>Se habilitado, o conector processa múltiplos itens em uma única operação em lote. Consulte <a href="#processamento-em-lote-batch-mode"><strong>Processamento em lote</strong></a> abaixo para mais detalhes.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Rollback on Error</strong></td><td>Quando <strong>Batch</strong> está habilitado, esta opção garante que todas as operações sejam revertidas se qualquer item falhar. Se desabilitado, as operações bem-sucedidas são confirmadas mesmo que outras falhem.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Batch Items</strong></td><td>Quando <strong>Batch</strong> está habilitado, especifica os itens do lote.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Blob As File</strong></td><td>Se habilitado, parâmetros BLOB para operações de Query ou Procedure devem receber um caminho de arquivo da mensagem de entrada.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Clob As File</strong></td><td>Se habilitado, parâmetros CLOB para operações de Query ou Procedure devem receber um caminho de arquivo da mensagem de entrada.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Charset</strong></td><td>O conjunto de caracteres para leitura de arquivos quando <strong>Clob As File</strong> estiver habilitado.</td><td>String</td><td>✅</td><td><code>UTF-8</code></td></tr><tr><td><strong>Type Properties</strong></td><td>Define tipos de dados específicos para parâmetros de procedimentos, especialmente para parâmetros <code>OUT</code>. Especifique a <strong>Key</strong> (índice do parâmetro), <strong>Type</strong> (por exemplo, <code>VARCHAR</code>), <strong>Out Parameter Name</strong> e <strong>Parameter Type</strong>.</td><td>List</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Custom Connection Properties</strong></td><td>Propriedades adicionais em formato chave-valor para a conexão JDBC. Cada propriedade deve estar em uma nova linha, por exemplo: <code>key=value</code>.</td><td>JSON</td><td>❌</td><td>N/A</td></tr></tbody></table>
{% endtab %}

{% tab title="Advanced Settings" %}

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Tipo</th><th>Suporta DB</th><th>Padrão</th></tr></thead><tbody><tr><td><strong>Pool Size By Actual Consumers</strong></td><td>Se habilitado, o tamanho do pool de conexões é definido pelo número de consumidores configurados no deployment do pipeline. Se desabilitado, assume o tamanho do deployment.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Exclusive DB Pool</strong></td><td><p>Se habilitado, cria um novo pool de conexões dedicado para este conector. Se desabilitado, ele pode compartilhar pools com outros conectores que usem exatamente a mesma configuração.</p><p></p><p><strong>Importante:</strong> Para compartilhar um pool, as propriedades de conexão personalizadas devem ser definidas na mesma ordem entre os conectores; caso contrário, um pool separado será criado.</p></td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Custom Pool</strong></td><td><p>Se habilitado, o pool de conexões é configurado usando <strong>Connection Maximum Lifetime</strong>, <strong>Minimum Idle Connections</strong> e <strong>Idle Connection Timeout</strong>. Se desabilitado, usa o parâmetro <strong>Keep Connection</strong>. </p><p></p><p><strong>Importante:</strong> Este recurso avançado deve ser usado com cautela. Veja a seção dedicada sobre <a href="#pool-de-conexoes"><strong>Pool de conexões</strong></a> abaixo.</p></td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Connection Maximum Lifetime</strong></td><td>(<strong>Somente Custom Pool</strong>) Define o tempo máximo de vida de uma conexão no pool. Conexões ativas não são aposentadas e são removidas apenas quando fechadas. O mínimo permitido é 30.000 ms; valores menores assumem o padrão de 1.800.000 ms (30 minutos).</td><td>Integer</td><td>✅</td><td><code>1800000</code></td></tr><tr><td><strong>Minimum Idle Connections</strong></td><td>(<strong>Somente Custom Pool</strong>) Define o número mínimo de conexões ociosas no pool. O máximo permitido depende do tamanho do deployment (10, 20 ou 40); valores maiores assumem o limite do deployment.</td><td>Integer</td><td>✅</td><td><code>10</code></td></tr><tr><td><strong>Idle Connection Timeout</strong></td><td>(<strong>Somente Custom Pool</strong>) Define o tempo máximo de inatividade de uma conexão no pool. Deve ser menor que <strong>Connection Maximum Lifetime</strong>, e <strong>Minimum Idle Connections</strong> deve ser menor que o tamanho do pool.</td><td>Integer</td><td>✅</td><td><code>600000</code></td></tr><tr><td><strong>Keep Connection</strong></td><td>Se habilitado, o pool mantém um número mínimo de conexões abertas (com base no <strong>Pool Size By Actual Consumers</strong>) e as renova a cada 30 minutos. Se desabilitado, o pool inicia vazio, abre conexões sob demanda, mantém por até 5 minutos e não as renova. Disponível apenas quando <strong>Custom Pool</strong> está desabilitado.</td><td>Booleano</td><td>❌</td><td><code>true</code></td></tr><tr><td><strong>Output Column From Label</strong></td><td>Se habilitado, as chaves do JSON de saída usarão o alias da coluna (label) da instrução <code>SELECT</code> em vez do nome original da coluna.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Connection Test Query</strong></td><td>Uma consulta SQL opcional (por exemplo, <code>SELECT 1</code>) que roda antes de estabelecer a conexão para validar sua integridade.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Raw SQL Statement</strong></td><td>Se habilitado, o parâmetro SQL Statement suporta queries dinâmicas usando Double Braces. Garanta medidas adequadas de segurança contra SQL injection. Consulte a <a href="#parametro-raw-sql-statement">seção abaixo</a> para mais detalhes.</td><td>Booleano</td><td>❌</td><td><code>false</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Documentation" %}

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Tipo</th><th>Padrão</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Campo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.</td><td>String</td><td>N/A</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## **Informações importantes**

#### **Credenciais e pool de conexões**

Quando credenciais são habilitadas, o pool de conexões é criado na execução do pipeline e fechado após sua conclusão. Pools podem ser compartilhados entre conectores se as mesmas configurações forem aplicadas.

#### **Apache Hive**

No Apache Hive, `updatecount` pode não estar disponível a menos que o controle de linhas esteja habilitado no servidor. Consulte os [bancos de dados suportados](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/supported-databases) para mais detalhes.

## **Parâmetros – Informações adicionais**

### **Variáveis de bind**

Variáveis de bind são parâmetros usados em consultas SQL para substituir valores fixos por valores dinâmicos. Elas permitem que a mesma consulta seja reutilizada com diferentes valores de entrada, reduzindo o risco de SQL Injection e melhorando a eficiência da execução. Esse recurso é suportado por vários bancos de dados relacionais, como Oracle e SQL Server.

Use [**Double Braces**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview) **(`{{ }}`)** para inserir valores dinâmicos em consultas SQL. Essa abordagem melhora a segurança (previne SQL Injection) e o desempenho (reaproveita planos de execução).

**Incorreto (sem variável de bind):**

```sql
SELECT * 
FROM CUSTOMER 
WHERE CUSTOMER_ID = 12345
```

**Correto (com variável de bind):**

```sql
SELECT * 
FROM CUSTOMER 
WHERE CUSTOMER_ID = {{ message.customerId }}
```

O DB V2 usa **JDBC PreparedStatements**, enviando consultas como:

1. Instrução SQL:\
   `SELECT * FROM CUSTOMER WHERE CUSTOMER_ID = ?`
2. Valor do parâmetro:\
   `CUSTOMER_ID = 12345`

Isso garante parametrização segura e reaproveitamento de planos de execução.

#### **Verificando se os binds foram aplicados**

Você pode confirmar se os binds estão sendo usados verificando as views de catálogo do banco de dados. Por exemplo, no Oracle:

```sql
SELECT sql_id, sql_text, bind_data, executions
FROM v$sql
WHERE sql_text LIKE '%CUSTOMER%'
ORDER BY last_load_time DESC;
```

Se `bind_data` estiver preenchido e o texto SQL contiver placeholders (`:1`, `:B1`), a consulta está usando variáveis de bind.

### **Parâmetro Raw SQL Statement**

Para adicionar mais flexibilidade ao usar o DB V2, você pode habilitar a opção **Raw SQL Statement**, pré-definir uma consulta e referenciá-la via **Double Braces** no parâmetro SQL Statement da seguinte forma:

1. Defina uma consulta usando o [**Template Transformer**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/tools/template-transformer).
2. Habilite a opção **Raw SQL Statement**.
3. Referencie a consulta pré-definida no parâmetro **SQL Statement**.

{% hint style="success" %}
Ao usar **Raw SQL Statement**, sempre defina consultas por meio do [**Template Transformer**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/tools/template-transformer). Isso permite validação de parâmetros usando FreeMarker e declaração de parâmetros via Double Braces. Note que esses parâmetros são resolvidos pelo DB V2, que prepara e valida instruções SQL (PreparedStatement) por padrão. Essa abordagem reduz o risco de SQL Injection.
{% endhint %}

Abaixo está uma comparação entre o uso recomendado do **Template Transformer** à esquerda (usando Double Braces na cláusula `WHERE`) e uma abordagem não recomendada à direita (usando FreeMarker na cláusula `WHERE`), que pode introduzir riscos de segurança.

{% columns %}
{% column %}
:white\_check\_mark: **Uso recomendado:**

{% code overflow="wrap" %}

```sql
SELECT * FROM
${table}
WHERE 0=0
<#if codigo??>AND CODE= {{ message._query.code }} </#if>
<#if cep??>AND ZIP_CODE= {{ message._query.zipCode }} </#if>
<#if name??>AND NAME= {{ message._query.name }} </#if>
```

{% endcode %}
{% endcolumn %}

{% column %}
:x: **Uso não recomendado:**

{% code overflow="wrap" %}

```sql
SELECT * FROM
${table}
WHERE 0=0
<#if codigo??>AND CODE=${code} </#if>
<#if cep??>AND ZIP_CODEand zip_code=${zipCode} </#if>
<#if name??>and name='${name}' </#if>
```

{% endcode %}
{% endcolumn %}
{% endcolumns %}

### **Parâmetro Key**

O parâmetro Key mapeia placeholders em instruções SQL para seus valores, especialmente em `Procedures` e consultas `INSERT` que lidam com dados CLOB/BLOB.

**Exemplo:**

```sql
INSERT INTO TABLE (MY_CLOB, MY_BLOB, MY_STRING)
VALUES ({{ message.clob }}, {{ message.blob }}, {{ message.string }})
```

**Mapeamento de índices:**

| Índice | Placeholder            |
| ------ | ---------------------- |
| 0      | `{{ message.clob }}`   |
| 1      | `{{ message.blob }}`   |
| 2      | `{{ message.string }}` |

Os índices sempre começam em 0 e seguem a ordem dos placeholders na instrução SQL.

## **DB V2 em ação**

### **Processamento em lote (Batch mode)**

Este modo executa consultas para arrays de objetos:

```json
[
  { "name": "Matthew", "type":"A" },
  { "name": "Jules", "type":"A" },
  { "name": "Raphael", "type":"B" }
]
```

**Exemplo de SQL:**

```sql
INSERT INTO TABLE VALUES ({{ item.name }}, {{ item.type }})
```

* Itera pelo array `items` e mapeia propriedades.
* Saída esperada:

```json
{ 
"totalSucceeded":3, 
"totalFailed":0 
}
```

**Tratamento de erros**:

1. **Erro único**:

```json
{ 
"totalSucceeded":1, 
"totalFailed":1, 
"error": "error1" 
}
```

2. **Múltiplos erros**:

```json
{ 
"totalSucceeded":1, 
"totalFailed":1, 
"errors": ["error1", "error2"] 
}
```

{% hint style="info" %}
O conteúdo da propriedade `errors` pode variar dependendo do driver do banco de dados. Alguns drivers não reportam todos os erros que ocorrem durante a execução em lote.
{% endhint %}

#### **Parâmetro Rollback on Error**

Se esta opção estiver **habilitada**, a Plataforma aplica o princípio do tudo ou nada nas operações em lote:

* O commit será realizado somente se todas as operações do lote tiverem sucesso.
* Se pelo menos uma operação falhar, um rollback é acionado e todas as operações do lote são revertidas, garantindo a consistência dos dados.

Se esta opção estiver **desabilitada**, o comportamento muda:

* É feito o commit de cada operação individualmente à medida que é bem-sucedida.
* Mesmo se uma ou mais operações falharem, os commits anteriores bem-sucedidos são preservados, podendo resultar em atualizações parciais no banco.

**Comportamento específico de driver**

Oracle e alguns outros drivers não conseguem retornar contagens consolidadas de execuções bem-sucedidas e falhas. Nesses casos, os resultados podem aparecer como:

```json
{
  "totalSucceeded": -1,
  "totalFailed": -1,
  "errors": ["error1", "error2"],
  "success": false
}
```

Firebird e drivers similares podem sub-reportar erros, às vezes retornando objetos que sugerem nenhum erro mesmo quando ocorreram falhas:

```json
{
  "totalSucceeded": 0,
  "totalFailed": 3,
  "errors": ["error1", "error2"],
  "success": false
}
```

{% hint style="success" %}
Sempre verifique a propriedade `success`. Um valor `false` significa que ocorreu pelo menos um erro, independentemente dos totais reportados.
{% endhint %}

### **Pool de conexões**

O tamanho do pool de conexões é definido automaticamente com base no **tamanho do deployment do pipeline**:

* Small: 10 conexões
* Medium: 20 conexões
* Large: 40 conexões

Pools são compartilhados entre todos os conectores DB (**DB V2** e [**Stream DB V3**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/stream-db-v3)) que se conectam ao mesmo banco dentro de um pipeline.

#### **Parâmetro Pool Size by Actual Consumers**

Você pode sobrescrever o comportamento padrão habilitando o parâmetro **Pool Size By Actual Consumers**:

* O tamanho do pool é definido pelo número de consumidores configurados manualmente na tela de deployment.
* É necessário habilitar essa propriedade em cada conector que deve adotar esse comportamento.

**Exemplo:** Em um pipeline Small com 5 consumidores, os conectores DB usam pool de tamanho 5.

{% hint style="danger" %}
Configurações manuais podem causar deadlocks se múltiplas chamadas concorrentes competirem pelo mesmo banco de dados.
{% endhint %}

#### **Parâmetro Exclusive Pool**

Por padrão, os pools são compartilhados entre conectores DB que acessam o mesmo banco. Se precisar de um pool isolado para um conector específico, habilite o parâmetro **Exclusive Pool**.

#### **Parâmetro Keep Connection**

Este parâmetro define como as conexões do pool são gerenciadas:

* **Habilitado**:
  * Conexões permanecem abertas e são renovadas a cada 30 minutos.
  * Adequado para cenários de alta disponibilidade (reduz overhead de abertura de conexões frequentemente).
* **Desabilitado**:
  * Conexões são abertas somente quando necessário.
  * Após o uso, permanecem ociosas por até 5 minutos antes de serem fechadas.
  * Mais eficiente para uso de baixa frequência.

#### **Parâmetro Custom Pool**

Para cenários avançados, você pode habilitar a opção **Custom Pool** para sobrescrever todos os padrões e definir:

* **Connection Maximum Lifetime**
* **Minimum Idle Connections**
* **Idle Connection Timeout**

{% hint style="danger" %}
Personalizar pools requer conhecimento aprofundado. Você deve considerar:

* Tamanho do deployment e número de réplicas.
* Uso de credenciais diferentes para o mesmo banco.
* Interação entre conectores DB em múltiplos pipelines.
* Se a opção **Exclusive Pool** está habilitada.

Configuração incorreta pode **degradar performance** ou causar **contenção de recursos**. Use esta opção apenas se tiver experiência em gerenciamento de pools e necessidade clara.
{% endhint %}

#### **Tecnologia subjacente**

O conector usa o framework **HikariCP** para gerenciar pools de conexão. Para configurações avançadas e melhores práticas, consulte a [documentação oficial do HikariCP](https://github.com/brettwooldridge/HikariCP).

## **Mais cenários de uso**

Consulte a documentação [DB V2: Cenários de uso](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/db-v2/db-v2-usage-scenarios) para tópicos avançados, desde definição de propriedades de conexão personalizadas até tratamento de tipos de dados customizados.