Stream DB V3

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

O Stream DB V3 permite estabelecer uma conexão com um serviço que suporta o protocolo JDBC (Java Database Connectivity) e executar instruções SQL (Structured Query Language). Para consultar quais os bancos de dados suportados por esse componente, leia a documentação Bancos de dados suportados.

Diferentemente do componente DB V1, o Stream DB foi desenvolvido para realizar execução em lotes, ou seja, cada retorno (linha resultante ou row) da instrução SQL executada é tratada individualmente através de um subpipeline, podendo conter seu próprio fluxo de processamento. Leia o artigo Subpipelines para saber mais.

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
Account	Para o componente fazer a autenticação a um serviço JDBC, é necessário usar uma account do tipo Basic ou Kerberos (veja o tópico Autenticação via Kerberos).	N/A	String
Database URL `(DB)`	URL (Uniform Resource Locator) para estabelecer conexão ao servidor de banco de dados com suporte ao protocolo JDBC. Este parâmetro aceita Double Braces.	jdbc:mysql://35.223.175.97/db-training	String
SQL Statement	Instrução SQL a ser executada.	select * from clientes LIMIT 2	String
Column Name	Caso haja um erro no processamento do subpipeline onProcess, o valor associado à coluna definida neste campo será adicionado à mensagem de erro, em um novo campo chamado "processedId" e que poderá ser manipulado pelo subpipeline onException.	codigo	String
Parallel Execution Of Each Iteration	Quando ativada, essa opção faz com que cada uma das passagens pelo subpipeline seja feita em paralelo, reduzindo o tempo de execução total. No entanto, não há qualquer garantia de que os itens sejam executados na ordem retornada pelo banco de dados.	False	Booleano
Blob As File	Se ativada, a opção faz com que os campos do tipo blob sejam armazenados no contexto do pipeline como arquivo; do contrário, os campos são armazenados como textos normais (strings) e codificados em base64.	False	Booleano
Clob As File	A opção faz com que os campos do tipo clob sejam armazenados no contexto do pipeline como arquivo; do contrário, os campos são armazenados como textos normais (strings).	False	Booleano
Charset	Essa opção é exibida apenas quando a opção Clob As File for ativada. Esse parâmetro permite configurar o encoding de arquivos clob.	UTF-8	String
Fail On Error	A habilitação desse parâmetro suspende a execução do pipeline apenas quando há uma ocorrência grave na estrutura da iteração, impedindo a sua conclusão por completo. A ativação do parâmetro Fail On Error não tem ligação com erros ocorridos nos componentes utilizados para a construção dos subpipelines (onProcess e onException).	False	Booleano
Custom Connection Properties	Propriedades de conexão específicas definidas pelo usuário.	N/A	String
Keep Connections	Se ativada, a opção vai manter as conexões com a base de dados por no máximo 30 minutos; do contrário, será por apenas 5 minutos.	True	Booleano
Advanced	Se ativada, as seguintes configurações estarão disponíveis:	False	Booleano
Pool Size By Actual Consumers	Se a opção estiver ativada, o número de pooled connections será equivalente ao número de consumers configurados durante a implantação do pipeline. Do contrário, o tamanho do pool é dado pelo tamanho de implantação do pipeline, independentemente do número de consumers.	False	Booleano
Exclusive DB Pool	Se a opção estiver ativada, um novo pool não-compartilhado sempre será criado para uso exclusivo deste componente. Do contrário, um pool poderá ser compartilhado entre componentes se a URL for a mesma.	False	Booleano
Output Column From Label	Para alguns bancos de dados, é importante manter esta opção ativada caso o seu SELECT esteja utilizando algum alias, pois dessa maneira garante-se que o nome da coluna será exibido da mesma forma que o alias configurado.	False	Booleano
Connection Test Query	Instrução SQL a ser executada antes que cada conexão seja estabelecida (i.e. `select 1 from dual`). Esse parâmetro é opcional e deve ser aplicado apenas a bancos de dados que não possuem 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

Account

Para o componente fazer a autenticação a um serviço JDBC, é necessário usar uma account do tipo Basic ou Kerberos (veja o tópico Autenticação via Kerberos).

N/A

String

Database URL (DB)

URL (Uniform Resource Locator) para estabelecer conexão ao servidor de banco de dados com suporte ao protocolo JDBC. Este parâmetro aceita Double Braces.

jdbc:mysql://35.223.175.97/db-training

String

SQL Statement

Instrução SQL a ser executada.

select * from clientes LIMIT 2

String

Column Name

Caso haja um erro no processamento do subpipeline onProcess, o valor associado à coluna definida neste campo será adicionado à mensagem de erro, em um novo campo chamado "processedId" e que poderá ser manipulado pelo subpipeline onException.

codigo

String

Parallel Execution Of Each Iteration

Quando ativada, essa opção faz com que cada uma das passagens pelo subpipeline seja feita em paralelo, reduzindo o tempo de execução total. No entanto, não há qualquer garantia de que os itens sejam executados na ordem retornada pelo banco de dados.

False

Booleano

Blob As File

Se ativada, a opção faz com que os campos do tipo blob sejam armazenados no contexto do pipeline como arquivo; do contrário, os campos são armazenados como textos normais (strings) e codificados em base64.

False

Booleano

Clob As File

A opção faz com que os campos do tipo clob sejam armazenados no contexto do pipeline como arquivo; do contrário, os campos são armazenados como textos normais (strings).

False

Booleano

Charset

Essa opção é exibida apenas quando a opção Clob As File for ativada. Esse parâmetro permite configurar o encoding de arquivos clob.

UTF-8

String

Fail On Error

A habilitação desse parâmetro suspende a execução do pipeline apenas quando há uma ocorrência grave na estrutura da iteração, impedindo a sua conclusão por completo. A ativação do parâmetro Fail On Error não tem ligação com erros ocorridos nos componentes utilizados para a construção dos subpipelines (onProcess e onException).

False

Booleano

Custom Connection Properties

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

N/A

String

Keep Connections

Se ativada, a opção vai manter as conexões com a base de dados por no máximo 30 minutos; do contrário, será por apenas 5 minutos.

True

Booleano

Advanced

Se ativada, as seguintes configurações estarão disponíveis:

False

Booleano

Pool Size By Actual Consumers

Se a opção estiver ativada, o número de pooled connections será equivalente ao número de consumers configurados durante a implantação do pipeline. Do contrário, o tamanho do pool é dado pelo tamanho de implantação do pipeline, independentemente do número de consumers.

False

Booleano

Exclusive DB Pool

Se a opção estiver ativada, um novo pool não-compartilhado sempre será criado para uso exclusivo deste componente. Do contrário, um pool poderá ser compartilhado entre componentes se a URL for a mesma.

False

Booleano

Output Column From Label

Para alguns bancos de dados, é importante manter esta opção ativada caso o seu SELECT esteja utilizando algum alias, pois dessa maneira garante-se que o nome da coluna será exibido da mesma forma que o alias configurado.

False

Booleano

Connection Test Query

Instrução SQL a ser executada antes que cada conexão seja estabelecida (i.e. select 1 from dual). Esse parâmetro é opcional e deve ser aplicado apenas a bancos de dados que não possuem 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

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 sobre parâmetros

Column Name

Veja o seguinte exemplo sobre a mensagem de erro em Column Name:

{
  "timestamp": 1600797662733,
  "error": "Error message",
  "code": 500,
  "processedId": "2"
}

Blob As File

Se Blob As File estiver ativado, os campos do tipo blob são armazenados como no exemplo a seguir:

// "Blob As File" true
{
  "id": 12,
  "blob": "d3X8YK.file",
}

Do contrário, os campos do tipo blob são armazenados como mostrado abaixo:

// "Blob As File" false
{
  "id": 12,
  "blob": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAeSURBVDhPY1Da6EMSYiBJNVDxqAZiQmw0lAZHKAEAaskfEED3lr0AAAAASUVORK5CYII="
}

Clob As File

Se Clob As File estiver ativado, os campos do tipo clob são armazenados como no exemplo a seguir:

// "Clob As File" true
{
  "id": 15,
  "clob": "f7X9AS.file",
}

Do contrário, os campos do tipo clob são armazenados como mostrado abaixo:

// "Clob As File" false
{
  "id": 15,
  "clob": "AAAAABBBBBCCCC”
}

Raw SQL Statement

Para trazer mais flexibilidade ao utilizar o Stream DB V3, 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 Stream DB V3, 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:

Tecnologia

Autenticação via Kerberos

Para realizar autenticação a um banco de dados via Kerberos é necessário:

informar uma conta (account) do tipo KERBEROS;
configurar um Kerberos principal;
configurar uma keytab (que deve ser a base64 do próprio arquivo keytab gerado).

Fluxo de Mensagens

Estrutura de mensagem disponível no subpipeline onProcess

Uma vez que a instrução SQL é executada, o subpipeline será disparado recebendo o resultado da execução por meio de uma mensagem na seguinte estrutura:

{  
    "coluna1": "dado1",   
    "coluna2": "dado2",  
    "coluna3": "dado3"
}

Saída com erro

{   
    "code": error_code,   
    "error": mensagem de erro,   
    "processId": the_id_column_value
}

Saída

Após a execução do componente, é retornada uma mensagem na seguinte estrutura:

{   
    "total": 0,   
    "success": 0,   
    "failed": 0
}

total: número total de linhas processadas.
success: número total de linhas processadas com sucesso.
failed: número total de linhas cujo processamento falhou.

Importante: para detectar se uma linha foi processada corretamente, cada subpipeline onProcess deve responder com { "success": true } a cada elemento processado.

O Stream DB V3 realiza processamento em lote. Consulte o artigo Processamento em lote para saber mais sobre este conceito.

Pool de conexão

Por padrão, utilizamos um pool com tamanho baseado nas configurações do pipeline implantado. Caso seja um pipeline Small, então o tamanho do pool será de 10; para o Medium, será de 20; e para o Large, de 40.

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

No exemplo da figura abaixo, foi configurado 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, é necessário habilitar o parâmetro Pool Size By Actual Consumers em todos os componentes existentes.

Tenha atenção redobrada 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 um determinado componente, habilite o parâmetro Exclusive DB Pool.

PreviousStored Procedure NextStream DB V1 (Descontinuado)

Last updated 4 days ago