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:
| Node | Engine | The agent writes |
|---|---|---|
| Postgres | PostgreSQL | One PostgreSQL statement |
| MySQL | MySQL / MariaDB | One MySQL / MariaDB statement |
| MongoDB | Your own external MongoDB | A 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
- Open your agent under Build → Agents.
- Click the + on the AI Agent's Action port and pick Postgres, MySQL, or MongoDB.
- Open the node and fill in the settings below — at minimum the Instruction and the Database connection.
Configuration

Postgres
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Tool Name | How the AI refers to this tool. Blank → derived from the node label. |
Instruction
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Instruction | Tell 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
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Database connection | Which Postgres connection to query. Connect one at Connections (Add → PostgreSQL) first. | |||
| Allowed schemas / tables | Optional. Comma-separated schemas or schema.table names to scope what the AI sees (e.g. "public.orders, public.customers"). Blank = whole database. |
Limits
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Statement timeout (ms) | Server-side cap on how long a single query may run. | 15000 | ||
| Row limit | Maximum rows returned to the AI (SELECTs are wrapped with an outer LIMIT). | 500 | ||
| Allow the AI to change data | Off: the AI can only read (queries run read-only). On: it may also insert, update and delete with the connection's permissions. | false |
MySQL
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Tool Name | How the AI refers to this tool. Blank → derived from the node label. |
Instruction
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Instruction | Tell 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
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Database connection | Which MySQL/MariaDB connection to query. Connect one at Connections (Add → MySQL) first. | |||
| Allowed tables | Optional. Comma-separated table names to scope what the AI sees (e.g. "orders, customers"). Blank = whole database. |
Limits
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Statement timeout (ms) | Server-side cap on how long a single query may run. | 15000 | ||
| Row limit | Maximum rows returned to the AI (SELECTs are wrapped with an outer LIMIT). | 500 | ||
| Allow the AI to change data | Off: the AI can only read (queries run read-only). On: it may also insert, update and delete with the connection's permissions. | false |
MongoDB
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Tool Name | How the AI refers to this tool. Blank → derived from the node label. |
Instruction
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Instruction | Tell 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
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Database connection | Which MongoDB connection to query. Connect one at Connections (Add → MongoDB) first. | |||
| Allowed collections | Optional. Comma-separated collection names to scope what the AI sees (e.g. "orders, customers"). Blank = whole database. |
Limits
| Field | What it does | Options | Default | Shown when |
|---|---|---|---|---|
| Operation timeout (ms) | Server-side cap (maxTimeMS) on how long a single operation may run. | 15000 | ||
| Document limit | Maximum documents returned to the AI. | 500 | ||
| Allow the AI to change data | Off: 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.

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
- Database Connectors — connect a PostgreSQL, MySQL, or MongoDB database and test it.
- AI Agent Node — the agent that decides when to call this tool.
- Trigger Nodes — the inbound entry point that starts a conversation.