PostgreSQL

Unified database plugin for PostgreSQL. Run raw SQL or use structured CRUD operations — query, find, insert, update, and delete — from a single node. Replaces the legacy separate db-query, db-find, db-insert, db-update, and db-delete plugins.

Setup

Add a PostgreSQL connection string as an environment variable on the Env Vars page:

| Variable | Description | |----------|-------------| | DATABASE_URL | PostgreSQL connection URL (e.g. postgresql://user:password@host:5432/database) |

The plugin uses asyncpg to connect and execute queries.

Operations

Each node run executes a single operation. Set Operation in the node settings, then fill in the fields shown for that operation.

query

Execute raw SQL with positional $1, $2, … parameters.

| Field | Type | Required | Description | |-------|------|----------|-------------| | operation | enum | Yes | query | | sql | string | Yes | Raw SQL query. Supports {{ }} bindings. | | params | JSON array | No | Positional parameters for the query (default []). |

find

Select rows from a table with optional filters, column selection, limit, and ordering.

| Field | Type | Required | Description | |-------|------|----------|-------------| | operation | enum | Yes | find | | table | string | Yes | Table name (e.g. users, orders). | | where | JSON object | No | WHERE conditions as key-value pairs. Supports {{ }} bindings. | | columns | string | No | Columns to return, comma-separated or * (default *). | | limit | number | No | Maximum number of rows to return. | | order_by | string | No | ORDER BY clause (e.g. created_at DESC). |

insert

Insert a row into a table.

| Field | Type | Required | Description | |-------|------|----------|-------------| | operation | enum | Yes | insert | | table | string | Yes | Table name. | | data | JSON object | Yes | Column-value mapping for the new row. Supports {{ }} bindings. |

update

Update rows matching a WHERE clause. WHERE is required — updates without conditions are rejected.

| Field | Type | Required | Description | |-------|------|----------|-------------| | operation | enum | Yes | update | | table | string | Yes | Table name. | | data | JSON object | Yes | Column-value mapping for the SET clause. | | where | JSON object | Yes | WHERE conditions. Must not be empty. |

delete

Delete rows matching a WHERE clause. WHERE is required — deletes without conditions are rejected.

| Field | Type | Required | Description | |-------|------|----------|-------------| | operation | enum | Yes | delete | | table | string | Yes | Table name. | | where | JSON object | Yes | WHERE conditions. Must not be empty. |

As an AI Agent Tool

Connect a PostgreSQL node to an AI Agent Tools handle to let the agent read and write your database.

Use Allowed Operations (Agent) to restrict which operations the agent can perform — for example, allow only find and query for read-only access, or exclude delete for safety. Operations not in the allowed list are rejected at runtime. This setting is excluded from the tool schema.

When used as a tool, the agent supplies operation and the relevant fields (table, sql, where, data, etc.) as tool arguments.

Output

All operations emit a result object on the result handle, accessible downstream as {{ postgres.* }}:

| Field | Type | Description | |-------|------|-------------| | rows | array | Result rows (for query and find; inserted/updated row for insert/update) | | affectedRows | number | Number of rows affected (for update and delete) | | success | boolean | Whether the operation succeeded |

{
  "rows": [{ "id": 1, "email": "[email protected]" }],
  "affectedRows": 0,
  "success": true
}

Access results in downstream nodes:

{{ postgres.rows[0].email }}
{{ postgres.affectedRows }}
{{ postgres.success }}