SQL Database (SQL_DATABASE)

Reads data from a database with an SQL query and passes the rows on as a list. Use it as a step, or connect it to an Agent’s Tools port so the agent can query the database when it needs to.

Category: Data Sources · Deployed: yes · Tool-capable: yes

Ports

Port Kind Purpose

Input (in_input)

Input

Optional. A JSON object from the previous module that can replace the query (see below)

Result (out_result)

Output

The rows as a JSON list

Tool (tool_mcp)

Tool

Connect it to an Agent’s Tools port to let the agent run the query itself

Properties

Field Required Meaning

Connection String (connectionString)

Yes

Where the database is and how to log in, for example jdbc:postgresql://host:5432/db?user=u&password=p. The field is hidden like a password. Use a database user that may only read

SQL Query (sqlQuery)

Yes

The query to run, for example SELECT name, total FROM orders WHERE status = 'OPEN'. It may contain ? placeholders for values (see below)

Description (description)

No, but needed as a tool

Tells the agent what data the query returns, so it knows when to use it. Not used as a step

Supported databases: the agent server can connect to PostgreSQL and MySQL (jdbc:postgresql://…, jdbc:mysql://…).

What the previous module can send (step)

When the previous module sends a JSON object, two fields are read:

Input field Effect

sqlQuery

Replaces the configured query for this run

parameters

A list of values for the ? placeholders in the query, in order

Anything else — plain text, or a JSON object without these fields — runs the configured query as it is.

What the agent can send (tool)

As a tool, the agent can call the module without any input. Then the configured query runs. The agent may also send its own sqlQuery and a parameters list, in the same way as above.

Result

The result is a JSON list with one entry per row. Each entry holds the row’s columns by name, for example [{"name": "Smith", "total": 120}, …]. A query that finds nothing gives [].

If the query fails, the result is not a list but {"error": "…"} with the database’s message. If the database cannot be reached, the message says so. The next module (or the agent) gets this text instead of rows.

Use cases

  • Scheduled report: Scheduler → SQL Database → Agent writes a summary → File Write.

  • As a tool: the agent looks up a customer or an order when the conversation needs it.

  • Row by row: SQL Database → Iterator, to handle each row on its own.

Notes

  • Use a database user that may only read. As a tool, the agent can send its own query, so the model decides what runs. Only the database user’s rights limit what it can do.

  • The connection string is not part of an export. It is left out when you export a pipeline, so enter it again after an import. Inside the app it is stored with the pipeline, and anyone who may edit the pipeline can reveal it in the field.

  • The database must be reachable from inside the agent server’s container. localhost there means the agent server itself, not your computer.

  • Keep results small. All rows go to the next module or into the agent’s context. Many rows make the agent slower and more expensive. Limit them in the query, for example with LIMIT 50.

  • Use ? placeholders with parameters instead of building the query from text. This keeps values such as names with quotes from breaking the query.