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

Parâmetro Descrição Valor padrão Tipo de dado

Parâmetro	Descrição	Valor padrão	Tipo de dado
Operation	Operação a ser realizada (Query ou Procedure).	Query	String
Account	Conta a ser utilizada pelo componente para se conectar. Contas suportadas: Basic e Kerberos.	N/A	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
Rollback On Error	Se esta opção estiver habilitada, os commits das operações são executados apenas se todas forem bem sucedidas. Caso contrário, será executada uma reversão de todas as operações em lote.	False	Booleano
Batch Items	Se Batch estiver ativado, especifique os itens do batch.	N/A	String
Fail On Error	Se a opção estiver habilitada, a execução do pipeline com erro será interrompida; do contrário, a execução do pipeline continua, e o resultado mostrará o valor false para a propriedade "success".	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
Custom Connection Properties	Propriedades específicas de conexão e banco de dados definidas pelo usuário.	N/A	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
Key	Faz referência a uma propriedade declarada atráves de expressão Double Braces no SQL Statement no caso de Procedures e INSERT Queries que tratam dos tipos de dados CLOB/BLOB. Veja mais sobre esse parâmetro na seção abaixo.	N/A	Inteiro
Type	O tipo de dado da propriedade que é declarado no SQL Statement.	VARCHAR	String
Out Parameter Name	Define o nome do parâmetro Out no caso de um Parameter Type tipo OUT ou INOUT.	N/A	String
Parameter Type	Define o tipo de uso da propriedade declarada no SQL Statement. As opções são IN, OUT ou INOUT.	IN	String
Keep Connection	Se a opção estiver habilitada, as conexões com o banco de dados serão mantidas por no máximo 30 minutos; caso contrário, serão mantidas por 5 minutos.	True	Booleano
Advanced	Permite definir uma Query a ser executada antes da definida no SQL Statement para garantir que a conexão com o banco de dados seja estabelecida e erros sejam evitados.	False	Booleano
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 componente. Se a opção estiver desativada, um pool poderá ser compartilhado entre os componentes se a URL for a mesma.	False	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
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 Name	Nome da conta a ser definida. O nome da conta deve ser gerado dinamicamente através do componente Store Account.	N/A	String
Scoped	Quando a opção estiver ativada, a conta armazenada é isolada para outro sub-processo. Nesse caso, os sub-processos verão sua própria versão dos dados da conta armazenada. Para saber mais sobre a funcionalidade Scoped, leia a documentação de Suporte a credenciais dinâmicas.	False	Booleano

Operation

Operação a ser realizada (Query ou Procedure).

Query

String

Account

Conta a ser utilizada pelo componente para se conectar. Contas suportadas: Basic e Kerberos.

N/A

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

Rollback On Error

Se esta opção estiver habilitada, os commits das operações são executados apenas se todas forem bem sucedidas. Caso contrário, será executada uma reversão de todas as operações em lote.

False

Booleano

Batch Items

Se Batch estiver ativado, especifique os itens do batch.

N/A

String

Fail On Error

Se a opção estiver habilitada, a execução do pipeline com erro será interrompida; do contrário, a execução do pipeline continua, e o resultado mostrará o valor false para a propriedade "success".

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

Custom Connection Properties

Propriedades específicas de conexão e banco de dados definidas pelo usuário.

N/A

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

Key

Faz referência a uma propriedade declarada atráves de expressão Double Braces no SQL Statement no caso de Procedures e INSERT Queries que tratam dos tipos de dados CLOB/BLOB. Veja mais sobre esse parâmetro na seção abaixo.

N/A

Inteiro

Type

O tipo de dado da propriedade que é declarado no SQL Statement.

VARCHAR

String

Out Parameter Name

Define o nome do parâmetro Out no caso de um Parameter Type tipo OUT ou INOUT.

N/A

String

Parameter Type

Define o tipo de uso da propriedade declarada no SQL Statement.

As opções são IN, OUT ou INOUT.

String

Keep Connection

Se a opção estiver habilitada, as conexões com o banco de dados serão mantidas por no máximo 30 minutos; caso contrário, serão mantidas por 5 minutos.

True

Booleano

Advanced

Permite definir uma Query a ser executada antes da definida no SQL Statement para garantir que a conexão com o banco de dados seja estabelecida e erros sejam evitados.

False

Booleano

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 componente. Se a opção estiver desativada, um pool poderá ser compartilhado entre os componentes se a URL for a mesma.

False

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

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 Name

Nome da conta a ser definida. O nome da conta deve ser gerado dinamicamente através do componente Store Account.

N/A

String

Scoped

Quando a opção estiver ativada, a conta armazenada é isolada para outro sub-processo. Nesse caso, os sub-processos verão sua própria versão dos dados da conta armazenada. Para saber mais sobre a funcionalidade Scoped, leia a documentação de Suporte a credenciais dinâmicas.

False

Booleano

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

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:

pageDB V2 - cenários de uso

PreviousCassandra DB NextDB V2 - cenários de uso

Last updated 4 months ago