Integration - SQL Query
Type identifier:
integration:sql:queryCategory: Integration Operations
Description
The Integration - SQL Query node executes SQL queries against a database connection established by an Integration - SQL Connect node. It supports parameterised queries to prevent SQL injection, validates queries for dangerous operations, and returns results matching a configurable schema.
Input Handles
Handle | Type | Description |
|---|---|---|
| SQL connection | Database connection from Integration - SQL Connect node. |
|
| (Dynamic) The SQL query to execute. |
| varies | Dynamic handles for query parameters. |
Output Handles
Handle | Type | Description |
|---|---|---|
|
| Array of result rows matching the row schema. |
| control | Triggered when query completes successfully. |
| control | Triggered when query fails. |
Configuration Options
Option | Type | Default | Description |
|---|---|---|---|
Connection Mode | enum |
| Use incoming connection handle or shared SQL credential. |
SQL Credential | credential id | - | Required when Connection Mode is shared credential. |
Query |
| - | SQL query with optional named parameters ( |
Parameters | array | - | Parameter definitions with names and types. |
Rows Schema | object schema | - | Schema defining the structure of result rows. |
Allow Dangerous Operations |
|
| Allow DDL operations (such as DROP and CREATE). |
Query Parameters
Parameters are referenced in queries using colon prefix (:paramName) and defined in the configuration:
Field | Type | Description |
|---|---|---|
Name |
| Parameter name (matches |
Type | schema | Data type of the parameter. |
Row Schema
Defines the expected structure of each result row. Properties should match the column names or aliases in the query.
Behaviour
- Resolves connection source:
handle: uses theconnectioninput handleshared_credential: resolves the selected SQL credential- if the shared credential is suspended and still within its cooldown window, the node fails immediately on the
errorpath without making an outbound connection attempt
- if the shared credential is suspended and still within its cooldown window, the node fails immediately on the
- Resolves query string and all parameter values
Validates the query:
- Maximum length: 100KB
- Blocks dangerous operations unless explicitly allowed
- Checks that all referenced parameters are defined
- Executes the query with parameters
- Maps results to the configured row schema
- Returns validated result rows
Shared credential mode updates connection health status automatically based on runtime outcomes. Repeated connection failures can place a credential into a suspended state. The cooldown starts at 10 seconds and doubles after each further connection failure, up to 10 minutes. Once the cooldown expires, the next run automatically probes the connection again. A successful connection clears suspension and resets the failure count.
Query Validation
Blocked operations (unless Allow Dangerous Operations is enabled):
DROP TABLE/DATABASE/SCHEMATRUNCATE TABLEALTER TABLE/DATABASE/SCHEMAGRANT/REVOKECREATE TABLE/DATABASE/SCHEMA/ROLE/USER
Parameterised Queries
Parameters prevent SQL injection:
SELECT * FROM users WHERE email = :email AND status = :statusResult Mapping
Results are converted to match the row schema:
- Column names (or aliases) are matched to schema property names
- Values are coerced to schema types
- Time values are parsed according to database format
Examples
Simple SELECT Query
Configuration:
- Query:
SELECT id, name, email FROM users WHERE active = true Rows Schema:
{ id: number, name: string, email: string }
Parameterised Query
Configuration:
- Query:
SELECT * FROM orders WHERE customer_id = :customerId AND created_at > :since Parameters:
customerId(number)since(datetime)
- Rows Schema: Order Schema
INSERT With Returning
Configuration:
- Query:
INSERT INTO logs (event, data) VALUES (:event, :data) RETURNING id, created_at Parameters:
event(string)data(object)
Rows Schema:
{ id: number, created_at: datetime }
Aggregate Query
Configuration:
- Query:
SELECT status, COUNT(*) as count FROM orders GROUP BY status Rows Schema:
{ status: string, count: number }