Skip to content

Database Actions ​

Give your agent a live line into your own database. A database action lets the agent read (and, where you allow it, write) against a database you have connected — the agent writes the query itself from your plain-language instruction and an automatically discovered summary of your schema, so you never hand-write SQL on the node.

There are three database actions, one per engine, under Actions → Databases in the node picker:

NodeEngineThe agent writes
PostgresPostgreSQLOne PostgreSQL statement
MySQLMySQL / MariaDBOne MySQL / MariaDB statement
MongoDBYour own external MongoDBA structured MongoDB operation (not a query string)

All three share the same configuration and the same safety rails — pick the one that matches the database you connected.

Connect the database first

A database action needs a connected database to point at. Add one once on the Connections page (Add → PostgreSQL, MySQL or MongoDB), then come back here to wire it into an agent. Full setup guide: Database Connectors.

How it works ​

You attach a database action to an agent, point it at a connected database, and it becomes a tool the agent can call during a conversation. When the agent decides it needs data, it writes a query, Perfox runs it against your database behind the safety rails, and hands the result — or the error — back to the agent to use in its reply.

Because the agent authors the query from a live summary of your schema, it adapts to your real tables and columns — you describe what you want in the node's instruction, not how to fetch it.

Adding the node ​

  1. Open your agent under Build → Agents.
  2. Click the + on the AI Agent's Action port and pick Postgres, MySQL, or MongoDB.
  3. Open the node and fill in the settings below — at minimum the Instruction and the Database connection.

Configuration ​

The Postgres action: Instruction, Database connection, Allowed schemas / tables, and Limits.

Postgres ​

FieldWhat it doesOptionsDefaultShown when
Tool NameHow the AI refers to this tool. Blank → derived from the node label.

Instruction ​

FieldWhat it doesOptionsDefaultShown when
InstructionTell the AI WHEN to use this tool AND WHAT to pass — which tables/fields/filters, and where the values come from in the conversation. The AI reads this plus the DB schema to write the query.

Connection ​

FieldWhat it doesOptionsDefaultShown when
Database connectionWhich Postgres connection to query. Connect one at Connections (Add → PostgreSQL) first.
Allowed schemas / tablesOptional. Comma-separated schemas or schema.table names to scope what the AI sees (e.g. "public.orders, public.customers"). Blank = whole database.

Limits ​

FieldWhat it doesOptionsDefaultShown when
Statement timeout (ms)Server-side cap on how long a single query may run.15000
Row limitMaximum rows returned to the AI (SELECTs are wrapped with an outer LIMIT).500
Allow the AI to change dataOff: the AI can only read (queries run read-only). On: it may also insert, update and delete with the connection's permissions.false

MySQL ​

FieldWhat it doesOptionsDefaultShown when
Tool NameHow the AI refers to this tool. Blank → derived from the node label.

Instruction ​

FieldWhat it doesOptionsDefaultShown when
InstructionTell the AI WHEN to use this tool AND WHAT to pass — which tables/fields/filters, and where the values come from in the conversation. The AI reads this plus the DB schema to write the query.

Connection ​

FieldWhat it doesOptionsDefaultShown when
Database connectionWhich MySQL/MariaDB connection to query. Connect one at Connections (Add → MySQL) first.
Allowed tablesOptional. Comma-separated table names to scope what the AI sees (e.g. "orders, customers"). Blank = whole database.

Limits ​

FieldWhat it doesOptionsDefaultShown when
Statement timeout (ms)Server-side cap on how long a single query may run.15000
Row limitMaximum rows returned to the AI (SELECTs are wrapped with an outer LIMIT).500
Allow the AI to change dataOff: the AI can only read (queries run read-only). On: it may also insert, update and delete with the connection's permissions.false

MongoDB ​

FieldWhat it doesOptionsDefaultShown when
Tool NameHow the AI refers to this tool. Blank → derived from the node label.

Instruction ​

FieldWhat it doesOptionsDefaultShown when
InstructionTell the AI WHEN to use this tool AND WHAT to pass — which collection, which fields, which filters. Mongo is schemaless, so this is your chance to point the AI at the right shape.

Connection ​

FieldWhat it doesOptionsDefaultShown when
Database connectionWhich MongoDB connection to query. Connect one at Connections (Add → MongoDB) first.
Allowed collectionsOptional. Comma-separated collection names to scope what the AI sees (e.g. "orders, customers"). Blank = whole database.

Limits ​

FieldWhat it doesOptionsDefaultShown when
Operation timeout (ms)Server-side cap (maxTimeMS) on how long a single operation may run.15000
Document limitMaximum documents returned to the AI.500
Allow the AI to change dataOff: the AI can only read (queries run read-only). On: it may also insert, update and delete with the connection's permissions.false

On all three, Statement timeout accepts 1,000–60,000 ms and Row limit accepts 1–2,000 rows.

A further piece of context — the schema summary — is discovered automatically and is not something you set. When the node runs, Perfox inspects the connected database (scoped to your Allowed scope) and attaches a compact summary of the tables, columns, and types to the tool, so the agent writes correct queries against your real schema. You never paste table or column names.

Scope is what the agent sees

Use Allowed scope to limit the agent to just the tables or schemas relevant to this agent's job. Anything outside the scope is left out of the schema summary, so the agent doesn't even know it exists.

Safety rails ​

A database action runs the agent's query behind several built-in guards, so a single query can't reach where it shouldn't, run away, or overwhelm the conversation:

  • Egress-guarded connection — every connection resolves and checks the host first, and refuses to connect to internal or private addresses. It also pins the resolved address for the life of the connection, so a host can't be swapped out mid-connect. Your database must be reachable on a public host.
  • Time cap — a query that exceeds the Statement timeout is cancelled by the database, with a matching client-side and connect timeout so nothing hangs.
  • Row cap — results are trimmed to your Row limit, and read queries are additionally wrapped so a huge result set is cut down at the source rather than pulled back in full.
  • Size cap — the result handed to the agent is capped in size, so an oversized payload can't flood the conversation.
  • Dangerous operations blocked — operations that could run arbitrary code on the database server or trigger unintended writes are rejected outright before anything reaches your database. For MongoDB this includes server-side-JavaScript and write-in-read operators such as $where, $function, $out, and $merge.
  • No query splicing — the query goes straight to the database driver with no string substitution, so there is no injection surface.
  • Scrubbed errors — when a query fails, the error is stripped of connection details (host, user, password) before it's fed back to the agent, and mapped to a short hint the agent can act on.
  • Fresh, isolated connection per call — each query opens its own connection and always closes it afterward.

Reads and writes ​

Each database action has an Allow the AI to change data checkbox under Limits, and it's off on a new node:

  • Off — the agent can only read; its queries run read-only.
  • On — it may also insert, update and delete, with whatever permissions the connection's database user has.

Because the agent writes the query itself, leave it off unless this agent's job is to change data.

The Limits section of a Postgres action: Statement timeout, Row limit, and the Allow the AI to change data checkbox, off.

Match the database user's grants too

Even with writes allowed, the agent can only do what the connected database user is permitted to do. Connect a user whose grants match exactly what this agent should touch — for example, read-only access to just the tables it needs.

When a query can't run ​

Two situations surface clearly rather than failing silently:

  • If the node hasn't been pointed at a database yet, it reports as not configured and the agent knows the tool isn't ready.
  • If the connected database's details are missing or invalid, the agent gets a missing connection result with guidance to fix the connection on the Connections page.

On any other error, the (scrubbed) message is fed back to the agent so it can read what went wrong, adjust its query, and try again.

See also ​