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 http://localhost:3009/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,
    "outputKey": "orders"
  }'

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 or database command. Uses `$1`, `$2`, etc. for parameters
`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
`outputKey`	string	No	Context key for query results

Parameterized Queries

Always use parameterized queries ($1, $2, etc.) instead of string interpolation for security:

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"]
}

Datasource Configuration

Store connection strings in org config:

bash

# PostgreSQL
curl -X POST http://localhost:3009/org-config \
  -H "X-Org-Id: acme-corp" \
  -d '{ "key": "db:warehouse_pg", "value": "postgresql://user:pass@host:5432/warehouse" }'

# MySQL
curl -X POST http://localhost:3009/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": {
    "since_date": "@input.start_date"
  },
  "outputKey": "orders"
}

Query results are stored at @orders — an array of row objects.

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	`postgresql://user:pass@host:5432/dbname`
MySQL	`mysql://user:pass@host:3306/dbname`
MongoDB	`mongodb://user:pass@host:27017/dbname`
Neo4j	`neo4j://user:pass@host:7687`

Security. DB actions execute queries with the permissions of the connection string's user. Use database users with the minimum necessary privileges — read-only users for query actions, limited write access for mutation actions. Never use admin credentials.

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