DB V2

Saiba mais sobre o conector DB V2 e como usá-lo na Digibee Integration Platform.

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.

Parâmetros

Configure o conector usando os parâmetros abaixo. Os campos que suportam expressões Double Braces estão marcados na coluna Suporta DB.

General

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Use Dynamic Account	Se habilitado, a conta é definida dinamicamente durante a execução. Se desabilitado, uma conta estática é selecionada da lista.	Booleano	❌	false
Scoped	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 Use Dynamic Account estiver habilitado.	Booleano	❌	false
Account Name	O nome da conta dinâmica usada pelo conector. Essa conta deve ter sido previamente configurada em um conector Store Account no pipeline para que este processo tenha efeito. Disponível apenas se o parâmetro Use Dynamic Account estiver habilitado.	String	✅	N/A
Account Type	O tipo de conta a ser usado pelo conector. As opções são: AWS V4, Basic, Kerberos e Azure Key.	String	❌	Basic
Account	As credenciais da conta usadas para conectar ao banco de dados.	Account	❌	N/A
Fail on Error	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 "success": false.	Booleano	❌	false

Operation

Advanced Settings

Documentation

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 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 ({{ }}) 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):

SELECT * 
FROM CUSTOMER 
WHERE CUSTOMER_ID = 12345

Correto (com variável de bind):

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:

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.

2. Habilite a opção Raw SQL Statement.

3. Referencie a consulta pré-definida no parâmetro SQL Statement.

Ao usar Raw SQL Statement, sempre defina consultas por meio do 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.

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.

✅ Uso recomendado:

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>

❌ Uso não recomendado:

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>

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:

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:

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

Exemplo de SQL:

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

• Itera pelo array items e mapeia propriedades.

• Saída esperada:

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

Tratamento de erros:

1. Erro único:

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

1. Múltiplos erros:

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

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.

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:

{
  "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:

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

Sempre verifique a propriedade success. Um valor false significa que ocorreu pelo menos um erro, independentemente dos totais reportados.

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) 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.

Configurações manuais podem causar deadlocks se múltiplas chamadas concorrentes competirem pelo mesmo banco de dados.

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

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.

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.

Mais cenários de uso

Consulte a documentação DB V2: Cenários de uso para tópicos avançados, desde definição de propriedades de conexão personalizadas até tratamento de tipos de dados customizados.