DB Actions

DB actions execute queries against your databases. Connection strings are stored encrypted in org config and referenced via orgconfig: prefix.

Registration

bash

curl -X POST https://your-hyphen.example.com/actions \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "get_pending_orders",
    "kind": "db",
    "description": "Fetch pending orders from the warehouse database",
    "datasource": "orgconfig:db:warehouse_pg",
    "query": "SELECT * FROM orders WHERE status = $1 AND created_at > $2",
    "params": ["pending", "@input.since_date"],
    "passthrough": true
  }'

Properties

Property	Type	Required	Description
`action_name`	string	Yes	Unique name for this action
`kind`	`"db"`	Yes
`datasource`	string	Yes	Connection string, typically `orgconfig:db:key_name`
`query`	string	Yes	SQL query with placeholders for the selected database
`params`	array	No	Ordered parameters for the query. Supports @path and literal values
`passthrough`	boolean	No	If true, raw query results are passed to context

Parameterized Queries

Always use parameterized queries instead of string interpolation. PostgreSQL uses $1, $2, and so on:

json

{
  "query": "SELECT * FROM customers WHERE region = $1 AND annual_revenue > $2",
  "params": ["@input.region", "@input.min_revenue"]
}

Parameters can be literal values or @path references:

json

{
  "query": "UPDATE invoices SET status = $1 WHERE invoice_id = $2",
  "params": ["reconciled", "@matched.0.invoice_id"]
}

MySQL, MariaDB, and Microsoft SQL Server use ? placeholders:

json

{
  "query": "SELECT * FROM customers WHERE region = ? AND annual_revenue > ?",
  "params": ["@input.region", "@input.min_revenue"]
}

Datasource Configuration

Store connection strings in org config:

bash

# PostgreSQL
curl -X POST https://your-hyphen.example.com/org-config \
  -H "X-Org-Id: acme-corp" \
  -d '{ "key": "db:warehouse_pg", "value": "postgres://user:pass@host:5432/warehouse" }'

# MySQL
curl -X POST https://your-hyphen.example.com/org-config \
  -H "X-Org-Id: acme-corp" \
  -d '{ "key": "db:crm_mysql", "value": "mysql://user:pass@host:3306/crm" }'

Then reference in the action:

json

{ "datasource": "orgconfig:db:warehouse_pg" }

The connection string is resolved at execution time and never stored in the action definition.

Usage in a Workflow

json

{
  "type": "get_pending_orders",
  "properties": {
    "outputKey": "orders"
  }
}

Start the workflow with input.since_date; the registered @input.since_date parameter resolves it at runtime. With passthrough: true, query results are stored at @orders as an array of row objects. properties.outputKey belongs to this workflow step, so another use of the same registered action can choose a different context key.

Usage as an Agent Tool

json

{
  "mode": "react",
  "objective": "Find all overdue invoices and summarize by vendor",
  "tools": [{ "type": "action", "name": "get_pending_orders" }, { "type": "action", "name": "get_vendor_info" }]
}

The agent can query the database to gather information during its reasoning process. Results are returned as observations the agent can analyze.

Supported Databases

Database	Datasource Format
PostgreSQL	`postgres://user:pass@host:5432/dbname`
MySQL	`mysql://user:pass@host:3306/dbname`
MariaDB	`mariadb://user:pass@host:3306/dbname`
Microsoft SQL Server	`mssql://user:pass@host:1433/dbname`

Security. DB actions use the permissions of the database user in the connection string. Give query actions read-only users and grant mutation actions only the writes they need. Do not use admin credentials.

→ Next: [Matcher Actions](/actions/matcher)