SQL Connector

1. Visão Geral

O componente SQL Connector (sql-connector) executa consultas SQL em um banco de dados relacional, permitindo buscar, inserir, atualizar ou remover dados.

Use quando o fluxo precisa ler ou gravar dados em um banco relacional (PostgreSQL, MySQL, SQL Server, etc., dependendo do driver JDBC disponível). Só funciona como ação de saída.

2. Pré-requisitos

• Um banco de dados relacional acessível pela plataforma, com a URL JDBC correspondente.
• Usuário e senha com permissão de acesso ao banco.

3. Autenticação e Conexão

Campo	Obrigatório	Tipo	Descrição	Exemplo
url	Sim	Texto	URL de conexão JDBC do banco de dados.	"jdbc:postgresql://db.exemplo.com:5432/clientes"
username	Sim	Texto	Usuário do banco de dados.	"app_user"
password	Sim	Texto	Senha do usuário.	"minhasenha"

⚠️ CONFIRMAR: os campos url, username e password são definidos uma única vez ao iniciar o fluxo — não podem variar por execução/mensagem, ou seja, todas as chamadas desse componente no mesmo step usam sempre a mesma conexão.

Conexões com a mesma combinação de url/username/password são reaproveitadas entre execuções (pool de conexões compartilhado).

4. Configuração / Operações Suportadas

O componente tem uma única operação: executar uma query SQL.

Campo	Obrigatório	Tipo	Descrição	Exemplo
query	Sim	Texto (SQL)	A consulta SQL a executar. Pode usar marcadores nomeados (:nome), substituídos pelos valores de variables.	"SELECT * FROM clientes WHERE id = :id"
variables	Não	Texto (chave1=valor1,chave2=valor2)	Valores a substituir nos marcadores da query.	"id=981"

Se a query for de leitura (SELECT), a resposta traz os registros encontrados. Se for de escrita (INSERT/UPDATE/DELETE), a resposta traz a quantidade de linhas afetadas.

5. Exemplos Práticos

Exemplo simples: buscar um cliente pelo ID.

Entrada:

{
  "clienteId": 981
}

Configuração do componente:

{
  "componentName": "sql-connector",
  "configurations": {
    "url": "jdbc:postgresql://db.exemplo.com:5432/clientes",
    "username": "app_user",
    "password": "{$.secrets.dbPassword}",
    "query": "SELECT id, nome, email FROM clientes WHERE id = :id",
    "variables": "id={$.body.clienteId}"
  }
}

Resposta:

{
  "result": [
    { "id": 981, "nome": "Maria Silva", "email": "maria@exemplo.com" }
  ]
}

Exemplo avançado: atualizar o status de um pedido no banco de dados.

Entrada:

{
  "pedidoId": 981,
  "novoStatus": "enviado"
}

Configuração do componente:

{
  "componentName": "sql-connector",
  "configurations": {
    "url": "jdbc:postgresql://db.exemplo.com:5432/pedidos",
    "username": "app_user",
    "password": "{$.secrets.dbPassword}",
    "query": "UPDATE pedidos SET status = :status WHERE id = :id",
    "variables": "status={$.body.novoStatus},id={$.body.pedidoId}"
  }
}

Resposta:

{
  "result": [{ "count": 1 }]
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"Not supported. This component not a trigger"	Tentativa de usar o SQL Connector como gatilho de entrada.	Usar o componente apenas como ação de saída no fluxo.
Falha de conexão ao banco	url, username ou password incorretos, ou o banco não está acessível pela rede.	Revisar as credenciais e a conectividade de rede até o banco.
Erro de sintaxe SQL propagado da exceção original	A query contém erro de sintaxe SQL.	Revisar a sintaxe da consulta.
Variáveis não substituídas na query	O formato de variables está incorreto (deve ser chave=valor separado por vírgula).	Revisar o formato de variables.