SQL Connector

1. Overview

The SQL Connector component (sql-connector) runs SQL queries against a relational database, allowing you to find, insert, update, or remove data.

Use it when the flow needs to read or write data in a relational database (PostgreSQL, MySQL, SQL Server, etc., depending on the available JDBC driver). Works only as an output action.

2. Prerequisites

• A relational database accessible by the platform, with the corresponding JDBC URL.
• A username and password with permission to access the database.

3. Authentication and Connection

Field	Required	Type	Description	Example
url	Yes	Text	Database's JDBC connection URL.	"jdbc:postgresql://db.example.com:5432/customers"
username	Yes	Text	Database username.	"app_user"
password	Yes	Text	User's password.	"mypassword"

TO CONFIRM: the url, username, and password fields are set once when the flow starts — they can't vary per run/message, meaning all calls to this component in the same step always use the same connection.

Connections with the same url/username/password combination are reused across runs (shared connection pool).

4. Configuration / Supported Operations

The component has a single operation: run a SQL query.

Field	Required	Type	Description	Example
query	Yes	Text (SQL)	The SQL query to run. Can use named placeholders (:name), replaced with values from variables.	"SELECT * FROM customers WHERE id = :id"
variables	No	Text (key1=value1,key2=value2)	Values to substitute the placeholders in query.	"id=981"

If the query is a read (SELECT), the response carries the found records. If it's a write (INSERT/UPDATE/DELETE), the response carries the number of affected rows.

5. Practical Examples

Simple example: find a customer by ID.

Input:

{
  "customerId": 981
}

Component configuration:

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

Response:

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

Advanced example: update an order's status in the database.

Input:

{
  "orderId": 981,
  "newStatus": "shipped"
}

Component configuration:

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

Response:

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

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
"Not supported. This component not a trigger"	Attempt to use SQL Connector as an entry trigger.	Use the component only as an output action in the flow.
Database connection failure	Incorrect url, username, or password, or the database isn't accessible on the network.	Review the credentials and network connectivity to the database.
SQL syntax error propagated from the original exception	The query contains a SQL syntax error.	Review the query's syntax.
Variables not substituted in the query	The variables format is incorrect (must be key=value comma-separated).	Review the format of variables.