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.

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)


Dê uma olhada nos cenários de uso suportados:

Cenário 1: Operação QUERY comando SELECT
Digamos que você tenha um banco de dados configurado e uma tabela com dados e que você queira invocar um DB V2 com uma query com o comando SELECT. Com isso, você terá acesso ao resultado da operação no pipeline através de um JSON.
     

Exemplo

1. Crie um pipeline e adicione um componente DB V2
2. Abra as configurações do componente
3. Selecione a operação QUERY
4. Escolha uma ACCOUNT para poder se autenticar no banco de dados
5. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb)
6. Defina um SQL STATEMENT  (ex.: SELECT * FROM CLIENTES)
7. Clique em CONFIRMAR para salvar as configurações do componente
8. Conecte o trigger ao DB V2
9. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
10. O resultado da query será apresentado:

{
  "data": [
    {
      "uf": "SP",
      "codigo": 1,
      "cidade": "Osasco",
      "logradouro": "Rua Laranjeiras",
      "name": "João Bosco",
      "due_date": "2019-03-27",
      "email": "joao.bosco@digibee.com.br",
      "cep": "XXXXX-XXX"
    },
    {
      "uf": "SP",
      "codigo": 2,
      "cidade": "São Paulo",
      "logradouro": "Rua Jõao Bosco",
      "name": "Roberto Carlos",
      "due_date": "2019-03-27",
      "email": "roberto.carlos@digibee.com.br",
      "cep": "XXXXX-XXX"
    }
  ],
  "updateCount": 0,
  "rowCount": 2
}

     
O resultado da query retorna um JSON com 3 propriedades em sua raiz: data, updateCount e rowCount.
    

  • data: vetor de objetos representando as linhas retornadas do banco de dados segundo a query definida. Cada elemento desse vetor contém propriedades que representam as colunas definidas na operação SELECT. Se a declaração fosse "SELECT name FROM CLIENTES", haveria apenas uma propriedade em cada um dos objetos no vetor data.
  • updateCount: indica quantas linhas da tabela foram afetadas pela query executada. Nesse exemplo o valor seria zero - já que a operação foi SELECT, nenhuma tabela foi afetada.
  • rowCount: indica quantas linhas foram retornadas pela query.
         

Cenário 2: Operação QUERY comando UPDATE
Digamos que você tenha um banco de dados configurado e uma tabela com dados e que você queira invocar um DB V2 com uma query com a operação UPDATE. Com isso, você terá acesso ao resultado desta operação no pipeline através de um JSON.
         
Exemplo

1. Crie um pipeline e adicione um componente DB V2
2. Abra as configurações do componente
3. Selecione a operação QUERY
4. Escolha uma ACCOUNT para poder se autenticar no banco de dados
5. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb)
6. Defina um SQL STATEMENT (ex.: UPDATE CLIENTES SET uf='SP' WHERE uf is null)
7. Clique em CONFIRMAR para salvar as configurações do componente
8. Conecte o trigger ao DB V2
9. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
10. O resultado da query será apresentado:

{
  "data": null,
  "updateCount": 5,
  "rowCount": 0
}

   

  • updateCount: nesse exemplo, fica confirmada a alteração em 5 linhas da tabela.


Cenário 3: Operação QUERY comando DELETE
Digamos que você tenha um banco de dados configurado e uma tabela com dados e que você queira invocar um DB V2 com uma query com a operação DELETE. Com isso, você terá acesso ao resultado desta operação no pipeline através de um JSON.

Exemplo

1. Crie um pipeline e adicione um componente DB V2
2. Abra as configurações do componente
3. Selecione a operação QUERY
4. Escolha uma ACCOUNT para poder se autenticar no banco de dados
5. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb)
6. Defina um SQL STATEMENT  (ex.: DELETE FROM CLIENTES WHERE codigo='111111')
7. Clique em CONFIRMAR para salvar as configurações do componente
8. Conecte o trigger ao DB V2
9. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
10. O resultado da query será apresentado:

{
  "data": null,
  "updateCount": 1,
  "rowCount": 0
}

  • updateCount: nesse exemplo, fica confirmado que 1 linha da tabela foi apagada.

     


Cenário 4: Operação QUERY comando INSERT
Digamos que você tenha um banco de dados configurado e uma tabela com dados e que você queira invocar um DB V2 com uma query com a operação INSERT. Com isso, você terá acesso ao resultado da operação no pipeline através de um JSON.
    
Exemplo:

1. Crie um pipeline e adicione um componente DB V2

2. Abra as configurações do componente
3. Selecione a operação QUERY
4. Escolha uma ACCOUNT para poder se autenticar no banco de dados
5. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb
6. Defina um SQL STATEMENT (ex.: INSERT INTO CLIENTES (name, email) VALUES ('My Name', 'myname@email.com'))
7. Clique em CONFIRMAR para salvar as configurações do componente
8. Conecte o trigger ao DB V2
9. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
10. O resultado da query será apresentado:

{
  "data": null,
  "updateCount": 1,
  "rowCount": 0
}

  • updateCount: nesse exemplo, fica confirmado que 1 linha foi criada na tabela.

     
Cenário 5: Manter a conexão em drivers antigos ou com baixa confiabilidade
Digamos que você tenha um banco de dados incompatível com JDBC 4.0 ou que falhe em manter uma conexão confiável e que você queira invocar um DB V2 com uma query qualquer, mas 20 minutos depois fazer a mesma chamada. Com isso, a conexão com o banco de dados não é perdida.
     

A opção ADVANCED > CONNECTION TEST QUERY permite definir uma query que é executada antes da query definida no SQL STATEMENT para garantir que a conexão foi estabelecida com o banco e evitar falhas.

Essa opção vai permitir que uma nova conexão seja aberta, caso haja falha no teste de conexão. Isso evitará problemas de conexões "presas" e timeouts causados por queries anteriores que receberam erro.

IMPORTANTE: essa opção deve ser considerada apenas para bancos de dados mais antigos (com versão de suporte ao jdbc < 4.0).

1. Crie um pipeline e adicione um componente DB V2
2. Abra as configurações do componente
3. Selecione a operação QUERY
4. Escolha uma ACCOUNT para poder se autenticar no banco de dados
5. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb)
6. Defina um SQL STATEMENT (ex.: INSERT INTO CLIENTES (name, email) VALUES ('My Name', 'myname@email.com'))
7. Conecte o trigger ao DB V2
8. Selecione a opção ADVANCED (mais opções serão apresentadas)
9. Defina uma CONNECTION TEST QUERY (ex.: SELECT version())
10. Clique em CONFIRMAR para salvar as configurações do componente
11. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
12. O resultado da query será apresentado

       

Cenário 6: Interromper a execução do pipeline em caso de falha
Digamos que você tenha um banco de dados configurado e uma tabela com dados e que você queira invocar um DB V2 com uma QUERY ou PROCEDURE caso a operação falhe interromper a execução do pipeline.
     

A opção FAIL ON ERROR permite que o pipeline interrompa a sua execução em caso de falha na invocação do DB V2.
        

     
Cenário 7: Acessar e escrever arquivos no contexto de banco de dados
Digamos que você tenha um banco de dados configurado e uma tabela com dados do tipo BLOB e que você queira invocar um DB V2 com uma QUERY ou PROCEDURE. Com isso, você consegue tanto escrever arquivos disponíveis no pipeline quanto acessar arquivos valores de um campo BLOB do banco de dados.
       

A opção BLOB AS FILE permite informar um caminho de arquivo para as operações com colunas do tipo BLOB - ou seja, invocar o comando INSERT e passar o caminho de um arquivo disponível no pipeline fará com que esse arquivo seja escrito no banco.
   
Caso o comando seja SELECT, o conteúdo do BLOB se torna um arquivo dentro do pipeline.
    

Exemplo: passo 1 (ler arquivo)

1. Crie um pipeline e adicione um componente DB V2
2. Abra as configurações do componente
3. Defina o nome como 'Read-file'
4. Selecione a operação QUERY
5. Escolha uma ACCOUNT para poder se autenticar no banco de dados
6. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb)
7. Defina um SQL STATEMENT (ex.: SELECT blob FROM CLIENTES WHERE id=78)
8. Ative a opção BLOB AS FILE
9. Clique em CONFIRMAR para salvar as configurações do componente
10. Conecte o trigger ao DB V2 (Read-file)
11. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
12. O resultado da query será apresentado:

{
  "data": [
    {
      "blob": "E4G17F.file"
    }
  ],
  "updateCount": 0,
  "rowCount": 1
}

     
Um arquivo chamado 'E4G17F.file' foi gerado e disponibilizado no pipeline.
    

Exemplo: passo 2 (escrever arquivo)


1. Adicione um componente DB V2
2. Abra as configurações do componente
3. Defina o nome como 'Write-file'
4. Selecione a operação QUERY
5. Escolha uma ACCOUNT para poder se autenticar no banco de dados
6. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb)
7. Defina um SQL STATEMENT (ex.: INSERT INTO CLIENTES (blob) VALUES ( {{ message.data.blob }} ))

Note que usamos a expressão em Double Braces: {{ message.data.blob }}
Através dela é possível acessar o resultado do último componente, nesse caso acessamos data que contem os resultados da query. Em seguida, acessamos blob, que é o nome do arquivo gerado. Ou seja, estamos passando o caminho para o arquivo 'E4G17F.file' no comando INSERT para o campo blob.

8. Ative a opção BLOB AS FILE
9. Clique em CONFIRMAR para salvar as configurações do componente
10. Conecte o DB V2 (Read-file) ao DB V2 (Write-file)
11. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
12. O resultado da query será apresentado:

{
  "data": null,
  "updateCount": 1,
  "rowCount": 0
}

     
O resultado indica que uma linha da tabela foi afetada. Nesse caso, o primeiro componente (Read-file) leu o conteúdo blob do banco de dados e criou um arquivo. Em seguida, o componente (Write-file) pegou esse arquivo disponível no pipeline e o inseriu no banco de dados em um novo registro.
     

Cenário 8: Executar uma procedure
Digamos que você tenha um banco de dados configurado com uma procedure existente e que você queira invocar um DB V2 em modo PROCEDURE. Com isso, você consegue executar uma procedure existente e obter o resultado da operação no pipeline através de um JSON.     

Exemplo

A seguinte procedure deve existir no banco de dados para esse exemplo:

CREATE 
PROCEDURE `proc_sum_one`(INOUT `num` INTEGER)
BEGIN  
    SET `num` = `num` + 1;
END

     
1. Crie um pipeline e adicione um componente DB V2
2. Abra as configurações do componente
3. Selecione a operação PROCEDURE
4. Escolha uma ACCOUNT para poder se autenticar no banco de dados
5. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb)
6. Defina um SQL STATEMENT ( ex.: call proc_sum_one({{ message.num }}) )

Note que usamos a expressão em Double Braces: {{ message.num }}
Através dela é possível acessar o resultado do último componente.

7. No campo TYPE PROPERTIES clique no botão ADD
8. Uma seção será apresentada conforme a imagem acima para que você defina os campos:

  • Key como 0 (cada Double Braces possui um índice, sendo que esse se refere ao primeiro)
  • TYPE como INTEGER
  • OUT PARAMETER NAME como result (define o parâmetro resultante da procedure)
  • PARAMETER TYPE como INOUT

9. Clique em CONFIRMAR para salvar as configurações do componente
10. Conecte o trigger ao DB V2
11. Abra o test-mode e passe um valor de entrada (ex.: { "num": 3 })
12. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
13. O resultado da query será apresentado:

{
  "data": {
    "result": 4
  },
  "success": true
}

         
       
Cenário 9: Definir propriedades personalizadas de conexão
Digamos que você tenha um banco de dados configurado e que você queira invocar um DB V2. Com isso, você consegue especificar propriedades personalizadas de conexão.
      

Exemplo

1. Abra as configurações do componente
2. Selecione a operação QUERY
3. Escolha uma ACCOUNT para poder se autenticar no banco de dados
4. Defina um DATABASE URL (ex.: jdbc:mysql://myserver/mydb)
5. Defina um SQL STATEMENT (e.g.) SELECT * FROM CLIENTES)
6. Defina o campo CUSTOM CONNECTION PROPERTIES (ex.: { "connectTimeout": 1 })
7. Clique em CONFIRMAR para salvar as configurações do componente
8. Conecte o trigger ao DB V2
9. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER)
10. O resultado da query será apresentado:

{
  "success": false,
  "message": "Could not establish connection to the database",
  "error": "java.sql.SQLNonTransientConnectionException: Could not connect to address=(host=xxxxx)(port=XXX)(type=master) : null"
}

     
Nesse caso, a propriedade específica de conexão connectTimeout foi definida como 1 (um segundo) para demonstrar que ela foi considerada e gerou um erro de conexão.
       

Cenário 10: Manter conexão ativa por 5 ou 30 minutos
Digamos que você tenha um banco de dados configurado e que você queira invocar um DB V2. Com isso, você pode optar por manter a conexão com o banco ativa por 5 ou 30 minutos.

A opção KEEP CONNECTION te permite estender o tempo padrão de 5 minutos para 30 minutos de conexão ativa com o banco de dados.

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 occorrê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.

Encontrou sua resposta?