DB V2 - cenários de uso
Saiba mais sobre como você pode usar o componente via Kerberos em alguns cenários.
Atualizado
Saiba mais sobre como você pode usar o componente via Kerberos em alguns cenários.
Atualizado
Dê uma olhada nos cenários de uso suportados:
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:
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.
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:
updateCount: nesse exemplo, fica confirmada a alteração em 5 linhas da tabela.
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:
updateCount: nesse exemplo, fica confirmado que 1 linha da tabela foi apagada.
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:
updateCount: nesse exemplo, fica confirmado que 1 linha foi criada na tabela.
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
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 na interrupção da 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.
Digamos que você tenha um banco de dados configurado e uma tabela com dados do tipo BLOB e/ou CLOB 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 e/ou CLOB do banco de dados.
As opções BLOB AS FILE e CLOB AS FILE permitem informar um caminho de arquivo para as operações com colunas do tipo BLOB e CLOB respectivamente - 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/CLOB 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 as opções BLOB AS FILE e/ou CLOB AS FILE (caso a opção CLOB AS FILE seja ativa, um novo campo CHARSET será exibido para que seja configurado o encoding do arquivo) 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:
Um arquivo chamado 'E4G17F.file' e outro chamado 'H2K89G.file' foram gerados e disponibilizados 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, clob) VALUES ( {{ message.data.blob }}, {{ message.data.clob }} ))
Note que expressões em Double Braces: {{ message.data.blob }} e {{ message.data.clob }} foram utilizadas.
Através delas é possível acessar o resultado do último componente. Nesse caso, data, que contém os resultados da query, foi acessada. Em seguida, blob e clob, que são os nomes dos arquivos gerados, foram acessados. Ou seja, está sendo passado o caminho para o arquivo 'E4G17F.file' e para o arquivo 'H2K89G.file' no comando INSERT para o campo blob e clob, respectivamente.
8. Ative a opção BLOB AS FILE e/ou CLOB AS FILE (caso a opção CLOB AS FILE seja ativa, um novo campo CHARSET será exibido para que seja configurado o encoding do arquivo)
9. No campo TYPE PROPERTIES clique no botão ADD
10. Uma seção será apresentada para que você defina os campos:
Key como 0 (cada Double Braces possui um índice, sendo que esse se refere ao primeiro)
TYPE como BLOB
OUT PARAMETER NAME em branco
PARAMETER TYPE como in
Key como 1 (cada Double Braces possui um índice, sendo que esse se refere ao segundo)
TYPE como CLOB
OUT PARAMETER NAME em branco
PARAMETER TYPE como in
11. Clique em CONFIRMAR para salvar as configurações do componente 12. Conecte o DB V2 (Read-file) ao DB V2 (Write-file) 13. Execute um teste no pipeline (você pode utilizar o comando CTRL + ENTER) 14. O resultado da query será apresentado:
O resultado indica que uma linha da tabela foi afetada. Nesse caso, o primeiro componente (Read-file) leu os conteúdos blob e clob do banco de dados e criou dois arquivos. Em seguida, o componente (Write-file) pegou esses arquivos disponíveis no pipeline e os inseriu no banco de dados em um novo registro.
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:
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 Painel de execução 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:
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:
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.
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.
Digamos que você tenha um banco de dados Oracle configurado com uma tabela que contenha dados de um tipo customizado e que você queira invocar um DB V2 para consultar esses dados.
Exemplo
Você tem a tabela criada com a seguinte estrutura:
E o tipo customizado OWNER criado da seguinte maneira:
CREATE TYPE OWNER AS OBJECT
Ao executar query abaixo:
Você tem o resultado:
Se o tipo customizado utilizar outros tipos customizado na sua estrutura, você teria o resultado com os dados aninhados da seguinte maneira:
IMPORTANTE: consultas de dados customizados não expõem os nomes dos campos informados dentro do tipo customizado, apenas a ordem dos campos.
No exemplo acima, o primeiro elemento do array "owner" corresponde ao campo "nome" e o segundo elemento ao campo "email", ambos definidos nessa respectiva ordem dentro do tipo OWNER.Para consultas via PROCEDURE, o parâmetro OUT PARAMETER NAME em TYPE PROPERTIES deve receber obrigatoriamente o nome do tipo customizado que, no exemplo acima, seria o valor OWNER.
Digamos que você tenha um banco de dados Oracle configurado com uma tabela que contenha dados de um tipo customizado (Struct) e que você queira invocar um DB V2 para inserir dados nessa tabela.
IMPORTANTE: o componente DB V2 não suporta Doubles Braces para resolver dados customizados (Struct) utilizando comandos INSERT e UPDATE.
Exemplo
Você tem os tipos customizados e a tabela criados com as seguintes estruturas:
CREATE OR REPLACE TYPE CONTACT AS OBJECT
CREATE OR REPLACE TYPE PERSON AS OBJECT
CREATE OR REPLACE TYPE DEPARTMENT AS OBJECT
CREATE TABLE EMPLOYEE
Para que esses dados sejam inseridos na tabela, é possível utilizar as seguintes estruturas:
Dados a serem inseridos:
Através de INSERT a partir do resultado de uma QUERY
Através de PROCEDURE:PROCEDURE previamente criada na base de dados
Chamada da PROCEDURE
Através de Script SQL
Digamos que você tenha um fluxo de integração que precise realizar duas queries diferentes em uma base de dados, dependendo de algumas regras de negócio:
QUERY 1:
QUERY 2:
O DB V2 conta com a funcionalidade Raw SQL Statement que permite que você referencie uma query completa através de uma declaração Double Braces, portanto a mesma referência pode ser aplicada a valores diferentes.
Para usar essa funcionalidade, as queries devem ser previamente configuradas por outro componente como o Template Transformer, e então referenciadas no DB V2.
Exemplo
1. Crie um pipeline e adicione o Template Transformer e o DB V2;
2. Abra as configurações do componente Template Transformer;
3. Ative a opção Preserve Original;
4. Defina o body:
5. Clique em Confirm para salvar as configurações do componente;
6. Abra as configurações do componente DB V2;
7. Selecione a operação Query;
8. Escolha uma account para permitir a autenticação na base de dados;
9. Defina a Database URL (ex.:jdbc:mysql://myserver/mydb);
10. Defina o SQL Statement como {{ message.query }};
11. Ative a opção Advanced;
12. Ative a opção Raw SQL Statement;
13. Clique em Confirm para salvar as configurações do componente;
14. Conecte o Template Transformer ao DB V2;
15. Conecte o trigger ao Template Transformer;
16. Execute um teste no pipeline passando um payload de entrada:
Payload para QUERY 1:
Payload para QUERY 2:
17. O resultado é exibido com base na query executada, como mostrado na sequência:
Resultado para QUERY 1:
Resultado para QUERY 2:
O resultado da query retorna um JSON com 3 propriedades em sua raiz: data, updateCount e rowCount.
data: objeto array representando as linhas retornadas da base de dados, de acordo com a query executada. Cada elemento deste array tem propriedades que representam as colunas definidas na operação Select. Caso a declaração seja "SELECT name FROM TABLE_1 WHERE ID = 123" ou "SELECT fullName FROM TABLE_2 WHERE CODE = 'ABC'", haveria apenas uma propriedade em cada um dos objetos no array de dados.
updateCount: indica quantas linhas da tabela foram afetadas pela query executada. No exemplo acima, o valor seria zero; uma vez que a operação escolhida foi Select, nenhuma tabela foi afetada.
rowCount: indica quantas linhas foram retornadas pela query.
IMPORTANTE: a query a ser referenciada através de Double Braces no DB V2 pode ser configurada previamente por outros componentes como JSON Generator ou Transformer (JOLT). Porém, ao usar o Template Transformer você pode combiná-la com a tecnologia FreeMarker para validar os dados antes de executar a target query e também aplicar mecanismos para prevenir ataques SQL injection no pipeline. A declaração Double Braces não é resolvida pelo Template Transformer mas pelo DB V2, que por padrão configura e valida os parâmetros da instrução SQL previamente (PreparedStatement). Isso significa que usar o Template Transformer em conjunto com o DB V2 é uma forma mais segura e simples de criar queries comparado a outros componentes.
