DB V2

Descubra mais sobre o componente DB V2 e saiba como utilizá-lo na Digibee Integration Platform.

O DB V2 efetua operações de Select, Insert, Delete e Update e também faz chamadas em Procedures, retornando os valores para uma estrutura JSON. Para consultar quais os bancos de dados suportados por esse componente, leia a documentação Bancos de dados suportados.

Parâmetros

Dê uma olhada nas opções de configuração do componente. Parâmetros suportados por expressões Double Braces estão marcados com (DB).

Aba General

Parâmetro	Descrição	Valor padrão	Tipo de dado
Use Dynamic Account	Quando a opção estiver ativada, o componente irá usar a conta dinamicamente. Quando estiver desativada, a conta será usada estaticamente.	False	Booleano
Account Type	Define o tipo de Conta a ser utilizada pelo componente. As opções são: Basic, AWS V4 e Kerberos.	Basic	String
Account	Conta a ser utilizada pelo componente para se conectar. Contas suportadas: Basic e Kerberos.	N/A	String
Fail On Error	Se a opção estiver ativada, a execução do pipeline com erro será interrompida. Do contrário, a execução do pipeline continua, mas o resultado irá mostrar um valor falso para a propriedade "success".	False	Booleano

Aba Operation

Parâmetro	Descrição	Valor padrão	Tipo de dado
Type	O tipo de dado da propriedade que é declarado no SQL Statement.	VARCHAR	String
Database URL	Define um Database URL.	jdbc:mysql://35.223.175.97/db-training	String
SQL Statement (DB)	Aceita qualquer SQL statement suportado pelo banco de dados subjacente. Expressões com Double Braces são permitidas. Ex.: {{ message.id }}.	SELECT DATE_FORMAT(SYSDATE(), '%Y-%m-%d') as DATA	String
Batch	Se a opção estiver habilitada, é realizado o processamento em lote.	False	Booleano
Blob As File	Se a opção estiver habilitada, todos os parâmetros Blob para operações Query ou Procedure deverão receber o caminho do arquivo.	False	Booleano
Clob As File	Se a opção estiver habilitada, todos os parâmetros Clob para operações Query ou Procedure deverão receber o caminho do arquivo.	False	Booleano
Charset	Nome do código dos caracteres para a leitura do arquivo.	UTF-8	String
Type Properties	Clique no botão Add para ativar os seguintes parâmetros adicionais: Key, Type, Out Parameter Name e Parameter Type.	N/A	Opções de Type Properties
Custom Connection Properties	Propriedades específicas de conexão e banco de dados definidas pelo usuário.	N/A	String

Aba Advanced Settings

Parâmetro	Descrição	Valor padrão	Tipo de dado
Pool Size By Actual Consumers	Se a opção estiver habilitada, o número de conexões agrupadas é igual ao número de consumidores configurados na implantação do pipeline. Se a opção estiver desativada, o tamanho do pool será determinado pelo tamanho da implantação do pipeline, independentemente do número de consumidores.	False	Booleano
Exclusive DB Pool	Se a opção estiver habilitada, um novo pool não compartilhado sempre é criado para uso exclusivo desse conector. Se a opção estiver desativada, um pool poderá ser compartilhado entre os componentes se a URL, credenciais e propriedades específicas de conexão forem as mesmas. Importante: propriedades específicas de conexão precisam ser declaradas na mesma ordem entre outros conectores para que o pool seja compartilhado, caso contrário será considerada como uma configuração diferente e um novo pool será criado.	False	Booleano
Custom Pool	Se a opção for habilitada, a configuração base do pool de conexões será feita baseada nos parâmetros Connection Maximum Lifetime, Minimum Idle Connections e Idle Connection Timeout. Se a opção for desabilitada, o pool será configurado com base no parâmetro Keep Connection. Importante: essa é uma funcionalidade avançada e deve ser usada com cautela. Confira abaixo a seção dedicada para o tópico Pool de Conexões.	False	Booleano
Connection Maximum Lifetime	Define o tempo de vida máximo de uma conexão no pool de conexões. Uma conexão em uso nunca será encerrada. Ela será removida apenas quando for fechada. O valor mínimo permitido é 30000 milissegundos (30 segundos). Se um valor menor for informado, será usado o valor padrão de 1800000 milissegundos (30 minutos). Esta opção está disponível apenas se o parâmetro Custom Pool estiver habilitado.	N/A	Integer
Minimum Idle Connections	Define o número mínimo de conexões idle a serem mantidas no pool. O valor máximo permitido é baseado no tamanho do deployment, ou seja, 10, 20 ou 40. Se um valor maior for informado, o máximo para o tamanho do deployment será usado. Esta opção está disponível apenas se o parâmetro Custom Pool estiver habilitado.	N/A	Integer
Idle Connection Timeout	Define o máximo de tempo no qual uma conexão pode ser mantida idle no pool. Para essa opção ter efeito: Seu valor deve ser inferior ao definido em Connection Maximum Lifetime. O valor configurado em Minimum Idle Connections deve ser inferior ao tamanho do pool (definido através de Pool Size By Actual Consumers). Esta opção está disponível apenas se o parâmetro Custom Pool estiver habilitado.	N/A	Integer
Keep Connection	Se a opção for habilitada, o pool de conexões sempre manterá um número mínimo de conexões abertas prontas para uso. Após 30 minutos, essas conexões serão renovadas. O número mínimo de conexões abertas é definido baseado no parâmetro Pool Size By Actual Consumers. Se a opção for desabilitada, o pool será criado vazio e conexões serão criadas sob demanda, sendo mantidas no pool por não mais que 5 minutos. Neste caso, as conexões não são renovadas. Esta opção está disponível apenas se o parâmetro Custom Pool estiver desabilitado.	True	Booleano
Output Column From Label	Para alguns bancos de dados, se seu Select usar um alias, você deve habilitar este sinalizador para que o nome da coluna seja exibido exatamente como o alias.	False	Booleano
Connection Test Query	SQL statement a ser usado antes de cada conexão ser estabelecida. Este é um parâmetro opcional e deve ser usado com bancos de dados que não fornecem informações confiáveis sobre o status da conexão.	N/A	String
Raw SQL Statement (DB)	Se a opção estiver ativada, o parâmetro SQL Statement permite o uso de queries dinâmicas através de declarações Double Braces. Ao utilizar essa funcionalidade, você deve garantir que o pipeline possua mecanismos de segurança contra instruções SQL indesejadas (SQL Injection). Veja mais sobre esse parâmetro na seção abaixo.	False	Booleano

Aba Documentation

Parâmetro	Descrição	Valor padrão	Tipo de dado
Documentation	Seção para documentar qualquer informação necessária sobre a configuração do conector e regras de negócio.	N/A	String

Informações importantes:

• Ao ativar o uso de credenciais, um pool de conexão é criado cada vez que o pipeline é executado e fechado quando a execução estiver completa. Os pools de conexão continuarão a ser comunicados entre os conectores do banco se a mesma configuração for aplicada entre eles.

• Atualmente, os parâmetros Use Dynamic Account, Account Name e Scoped podem ser usados apenas no Pipeline Engine v2 e estão disponíveis em fase Beta Restrito. Para saber mais, leia o artigo Progama Beta.

• Em casos onde um banco de dados Apache Hive é usado, os dados de Updatecount podem estar indisponíveis devido a uma característica do sistema. Essa informação estará disponível apenas se o controle do updated row count estiver habilitado no servidor Apache Hive. Para mais informações sobre suporte Apache Hive para a Digibee Integration Platform, leia o artigo Banco de dados suportados.

Informações adicionais de parâmetros

Key

O parâmetro Key faz referência a uma propriedade declarada através de uma expressão Double Braces no SQL Statement em caso de Procedures e INSERT Queries que tratam dos tipos de dados CLOB/BLOB. Toda declaração Double Braces tem um index que deve ser usado para configurar esse parâmetro.

Exemplo:

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

Nesse caso, temos index 0 para {{ message.clob }}, 1 para {{ message.blob }} e 2 para {{ message.string }} .

Raw SQL Statement

Para trazer mais flexibilidade ao utilizar o DB V2, podemos ativar a opção Raw SQL Statement, configurar previamente uma query e referenciá-la via Double Braces no parâmetro SQL Statement da seguinte maneira:

Query definida previamente via Template Transformer

Ativação do Raw SQL Statement

Query referenciada no parâmetro SQL Statement

Importante: como boa prática, recomendamos fortemente que ao ativar a opção Raw SQL Statement, as queries sejam definidas previamente através do componente Template Transformer. O uso do Template Transformer permite validar parâmetros através da tecnologia FreeMarker e também a declaração de parâmetros via Double Braces. Estes parâmetros não são resolvidos pelo Template Transformer e sim pelo componente DB V2, que por padrão configura e valida os parâmetros da instrução SQL previamente (PreparedStatement). Ao aplicar essas medidas de segurança, você diminui os riscos de ataques do tipo SQL Injection.

Na imagem abaixo, temos à esquerda um exemplo do uso recomendado do componente (com o Double Braces na cláusula WHERE, no destaque verde); e à direita um exemplo do uso não recomendado (com o FreeMarker na cláusula WHERE, no destaque vermelho) que pode trazer riscos à segurança do pipeline:

DB V2 em Ação

Batch mode

Quando for necessário realizar um processamento em lote de algumas instruções, você pode realizar chamadas em modo batch nas queries.

Exemplo

Digamos que você precise informar no componente um array de objetos, que serão utilizados nessa execução em batch:

Itens

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

E na instrução SQL, você deverá informá-lo da seguinte maneira:

SQL

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

Quando você utiliza expressões em Double Braces {{ item.name }}, uma iteração é feita dentro do array (informado em itens) e uma propriedade correspondente é buscada dentro do objeto. Nesse caso, a propriedade é "name".

Após a execução, 3 registros são inseridos. O retorno esperado é:

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

Caso uma das execuções falhe, será retornado um objeto com a propriedade "error":

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

Caso uma das execuções falhe, será retornado um objeto com a propriedade "errors":

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

Importante: os erros retornados na propriedade “errors” variam conforme o driver do banco. Alguns drivers não retornam todos os erros ocorridos durante a execução em modo batch.

Rollback On Error

Se essa opção estiver ativada, os commits das operações serão realizados apenas se todas elas forem bem sucedidas. Do contrário, será feito o rollback de todas as operações batch.

Se a opção estiver inativa, então o commit e as alterações bem sucedidas por commit serão feitas mesmo que ocorra alguma falha entre as execuções.

Importante: para alguns bancos de dados, principalmente para o Oracle, não é possível retornar o número consolidado execuções bem ou mal sucedidas.

Caso algum erro ocorra, um objeto contendo todos os erros será retornado (dentro da propriedade "errors") e consolidado com o valor -1 também será retornado:

{ 
    "totalSucceeded":-1, 
    "totalFailed":-1,
    "errors": ["erro1", "error2"], 
    "success": false
}

Para outros bancos, como o Firebird, a ocorrência de erros não é informada. Portanto, um objeto sem nenhum erro pode ser retornado mesmo que tenha ocorrido uma falha:

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

Para esses casos de erro no Batch Mode, não deixe de analisar a propriedade "success". Se ela retornar "false", significa que pelo menos um erro ocorreu durante a execução.

Pool de conexão

Por padrão, utilizamos um pool de tamanho baseado nas configurações do pipeline implantado. Por exemplo, caso seja um pipeline SMALL, então o tamanho do pool será de 10. Para o MEDIUM o tamanho seria de 20 e para o LARGE seria de 40.

É possível gerenciar o tamanho do pool na hora da implantação também. Para isso, é necessário habilitar a propriedade Pool Size By Actual Consumers no componente. Com isso, é utilizado o que for configurado manualmente na tela de implantação.

Veja na figura abaixo a configuração de um pipeline SMALL com 5 consumers. Se você quiser que o pool dos componentes de banco de dados (DB V2 e Stream DB V3) utilize esse tamanho, será preciso habilitar a propriedade “Pool Size By Actual Consumers” em todos os componentes existentes:

Importante: atenção ao configurar o tamanho do pool manualmente para que não ocorra nenhum deadlock em chamadas concorrentes ao mesmo banco.

O nosso pool é compartilhado entre os componentes de banco de dados que acessam o mesmo banco de dados dentro do pipeline. Caso seja necessário um pool exclusivo para determinado componente, habilite a propriedade “Exclusive Pool”.

Customizando o Pool de Conexões

Por padrão, o conector definirá como as conexões são gerenciadas no pool com base no parâmetro Keep Connection. Esta configuração visa facilitar a configuração do pool de conexões para cenários em que, por exemplo, alta disponibilidade é necessária ou o oposto disso.

Se habilitado, as conexões são mantidas abertas no pool o tempo todo e são renovadas após 30 minutos. Isso pode ser usado para cenários de alta disponibilidade reduzindo custo de abrir novas conexões frequentemente.

No entanto, se tivermos o cenário oposto onde as conexões são necessárias em intervalos de tempo mais espaçados, você pode desativar o parâmetro para configurar o pool sem conexões abertas previamente e abri-las apenas quando for realmente necessário. Após a conexão ser utilizada, ela será mantida no pool por no máximo 5 minutos e não será renovada.

Embora isso signifique que você não precisa se preocupar com a configuração do pool de conexões, esta opção padrão pode não ser a melhor para alguns casos.

Para ter mais flexibilidade na configuração do pool, você pode ativar a opção Custom Pool. Esta opção ignora a configuração padrão e torna possível definir uma configuração customizada.

Nesse caso, precisamos definir os três parâmetros abaixo (que são definidos implicitamente na configuração padrão):

• Connection Maximum Lifetime

• Minimum Idle Connections

• Idle Connection Timeout

Configurar um pool de conexões pode ser uma tarefa difícil, pois se espera um conhecimento mais aprofundado sobre o tema. Quando aplicado no contexto da Digibee Integration Platform, você deve considerar as variáveis que podem afetar o desempenho do pool.

Coisas como o tamanho do deployment e suas réplicas, acessar os mesmos bancos de dados usando credenciais e propriedades distintas nos conectores de banco de dados dentro dos mesmos e diferentes pipelines e a opção exclusiva de pool de banco de dados nos conectores de banco de dados impactam diretamente em como o pool de conexões deve ser configurado.

Com base em tudo mencionado acima, é altamente recomendável habilitar a opção Custom Pool se tiver conhecimento sobre o tema e se for realmente necessário.

O conector usa o framework HikariCP para gerenciar os pools de conexão. Informações adicionais sobre o tema podem ser encontradas em sua documentação oficial.

Tecnologia

Autenticação via Kerberos

É possível realizar autenticação via Kerberos em componentes de banco de dados. Para isso, basta você:

• informar uma conta do tipo KERBEROS

• configurar um Kerberos principal

• configurar uma keytab (que deve ser a base64 do próprio arquivo keytab gerado)

Mais cenários de uso com DB V2

Veja na documentação a seguir como usar o DB V2 em diferentes cenários:

DB V2 - cenários de uso