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

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Type	O tipo de dado da propriedade declarado na instrução SQL.	String	❌	Query
Database URL	A string de conexão JDBC para o banco de dados de destino.	String	✅	jdbc:mysql://host:port/database
SQL Statement	A consulta SQL ou chamada de procedimento a ser executada. Valores dinâmicos podem ser inseridos usando Double Braces.	String	✅	SELECT DATE_FORMAT(SYSDATE(), '%Y-%m-%d') as DATA
Batch	Se habilitado, o conector processa múltiplos itens em uma única operação em lote. Consulte Processamento em lote abaixo para mais detalhes.	Booleano	❌	false
Rollback on Error	Quando Batch 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.	Booleano	❌	false
Batch Items	Quando Batch está habilitado, especifica os itens do lote.	String	✅	N/A
Blob As File	Se habilitado, parâmetros BLOB para operações de Query ou Procedure devem receber um caminho de arquivo da mensagem de entrada.	Booleano	❌	false
Clob As File	Se habilitado, parâmetros CLOB para operações de Query ou Procedure devem receber um caminho de arquivo da mensagem de entrada.	Booleano	❌	false
Charset	O conjunto de caracteres para leitura de arquivos quando Clob As File estiver habilitado.	String	✅	UTF-8
Type Properties	Define tipos de dados específicos para parâmetros de procedimentos, especialmente para parâmetros OUT. Especifique a Key (índice do parâmetro), Type (por exemplo, VARCHAR), Out Parameter Name e Parameter Type.	List	❌	N/A
Custom Connection Properties	Propriedades adicionais em formato chave-valor para a conexão JDBC. Cada propriedade deve estar em uma nova linha, por exemplo: key=value.	JSON	❌	N/A

Advanced Settings

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Pool Size By Actual Consumers	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.	Booleano	❌	false
Exclusive DB Pool	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. Importante: 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.	Booleano	❌	false
Custom Pool	Se habilitado, o pool de conexões é configurado usando Connection Maximum Lifetime, Minimum Idle Connections e Idle Connection Timeout. Se desabilitado, usa o parâmetro Keep Connection. Importante: Este recurso avançado deve ser usado com cautela. Veja a seção dedicada sobre Pool de conexões abaixo.	Booleano	❌	false
Connection Maximum Lifetime	(Somente Custom Pool) 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).	Integer	✅	1800000
Minimum Idle Connections	(Somente Custom Pool) 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.	Integer	✅	10
Idle Connection Timeout	(Somente Custom Pool) Define o tempo máximo de inatividade de uma conexão no pool. Deve ser menor que Connection Maximum Lifetime, e Minimum Idle Connections deve ser menor que o tamanho do pool.	Integer	✅	600000
Keep Connection	Se habilitado, o pool mantém um número mínimo de conexões abertas (com base no Pool Size By Actual Consumers) 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 Custom Pool está desabilitado.	Booleano	❌	true
Output Column From Label	Se habilitado, as chaves do JSON de saída usarão o alias da coluna (label) da instrução SELECT em vez do nome original da coluna.	Booleano	❌	false
Connection Test Query	Uma consulta SQL opcional (por exemplo, SELECT 1) que roda antes de estabelecer a conexão para validar sua integridade.	String	✅	N/A
Raw SQL Statement	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 seção abaixo para mais detalhes.	Booleano	❌	false

Documentation

Parâmetro	Descrição	Tipo	Padrão
Documentation	Campo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.	String	N/A

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.