SQL Connector

1. Visión General

El componente SQL Connector (sql-connector) ejecuta consultas SQL en una base de datos relacional, permitiendo buscar, insertar, actualizar o eliminar datos.

Úsalo cuando el flujo necesita leer o grabar datos en una base relacional (PostgreSQL, MySQL, SQL Server, etc., dependiendo del driver JDBC disponible). Solo funciona como acción de salida.

2. Prerrequisitos

• Una base de datos relacional accesible por la plataforma, con la URL JDBC correspondiente.
• Usuario y contraseña con permiso de acceso a la base.

3. Autenticación y Conexión

Campo	Obligatorio	Tipo	Descripción	Ejemplo
url	Sí	Texto	URL de conexión JDBC de la base de datos.	"jdbc:postgresql://db.ejemplo.com:5432/clientes"
username	Sí	Texto	Usuario de la base de datos.	"app_user"
password	Sí	Texto	Contraseña del usuario.	"micontrasena"

A CONFIRMAR: los campos url, username y password se definen una única vez al iniciar el flujo — no pueden variar por ejecución/mensaje, es decir, todas las llamadas de este componente en el mismo step usan siempre la misma conexión.

Las conexiones con la misma combinación de url/username/password se reutilizan entre ejecuciones (pool de conexiones compartido).

4. Configuración / Operaciones Soportadas

El componente tiene una única operación: ejecutar una consulta SQL.

Campo	Obligatorio	Tipo	Descripción	Ejemplo
query	Sí	Texto (SQL)	La consulta SQL a ejecutar. Puede usar marcadores con nombre (:nombre), reemplazados por los valores de variables.	"SELECT * FROM clientes WHERE id = :id"
variables	No	Texto (clave1=valor1,clave2=valor2)	Valores a reemplazar en los marcadores de la query.	"id=981"

Si la consulta es de lectura (SELECT), la respuesta trae los registros encontrados. Si es de escritura (INSERT/UPDATE/DELETE), la respuesta trae la cantidad de filas afectadas.

5. Ejemplos Prácticos

Ejemplo simple: buscar un cliente por su ID.

Entrada:

{
  "clienteId": 981
}

Configuración del componente:

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

Respuesta:

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

Ejemplo avanzado: actualizar el estado de un pedido en la base de datos.

Entrada:

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

Configuración del componente:

{
  "componentName": "sql-connector",
  "configurations": {
    "url": "jdbc:postgresql://db.ejemplo.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}"
  }
}

Respuesta:

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

6. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"Not supported. This component not a trigger"	Intento de usar el SQL Connector como disparador de entrada.	Usar el componente solo como acción de salida en el flujo.
Falla de conexión a la base	url, username o password incorrectos, o la base no es accesible por la red.	Revisar las credenciales y la conectividad de red hacia la base.
Error de sintaxis SQL propagado de la excepción original	La query contiene un error de sintaxis SQL.	Revisar la sintaxis de la consulta.
Variables no reemplazadas en la consulta	El formato de variables es incorrecto (debe ser clave=valor separado por comas).	Revisar el formato de variables.