# 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](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/supported-databases.md).

## **Parâmetros**

Configure o conector usando os parâmetros abaixo. Os campos que suportam [expressões Double Braces](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md) 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="/pages/iulYYuz29bvfGjceZb4e"><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="/spaces/cO0A6g1dOsu8BiHYqO67/pages/fS1QLzAg8rGSSJFwtrvy">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](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/supported-databases.md) 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**](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md) **(`{{ }}`)** 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**](/documentation/connectors-and-triggers/pt-br/connectors/tools/template-transformer.md).
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**](/documentation/connectors-and-triggers/pt-br/connectors/tools/template-transformer.md). 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**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/stream-db-v3.md)) 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](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/db-v2/db-v2-usage-scenarios.md) para tópicos avançados, desde definição de propriedades de conexão personalizadas até tratamento de tipos de dados customizados.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/db-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.