Actions3
Overview
This node allows executing SQL queries against a PostgreSQL database. It supports running arbitrary SQL commands, which makes it highly flexible for interacting with your database directly from n8n workflows. Common use cases include fetching data with SELECT statements, performing complex joins, filtering records, or running any custom SQL logic that is not covered by simpler insert or update operations.
For example, you might use this node to:
- Retrieve product information where quantity and price meet certain criteria.
- Run batch queries in a single transaction to ensure atomicity.
- Execute parameterized queries using dynamic input values from previous workflow steps.
Properties
| Name | Meaning |
|---|---|
| Query | The SQL query string to execute. Supports n8n expressions and positional parameters like $1, $2 which can be linked to query parameters. Example: SELECT id, name FROM product WHERE quantity > $1 AND price <= $2. |
| Additional Fields | A collection of optional settings: |
| - Mode | How queries are sent to the database: • Independently — each query runs separately. • Multiple Queries (default) — sends multiple queries at once. • Transaction — executes all queries within a single transaction. |
| - Output Large-Format Numbers As | Controls how large numeric types (NUMERIC, BIGINT) are returned: • Numbers — as JavaScript numbers. • Text (default) — as strings to avoid precision loss for very large numbers. |
| Query Parameters | Comma-separated list of property names from input data to be used as parameters for the query placeholders ($1, $2, etc.). For example: quantity,price. |
Output
The node outputs an array of JSON objects representing the rows returned by the executed SQL query. Each object corresponds to a row, with keys matching the column names selected in the query.
If the query affects rows but does not return data (e.g., UPDATE without RETURNING), the output may be empty or contain metadata depending on the query.
Large numeric fields (NUMERIC, BIGINT) are output either as numbers or text strings based on the "Output Large-Format Numbers As" setting to prevent precision issues.
No binary data output is produced by this node.
Dependencies
- Requires a PostgreSQL database connection configured via credentials containing host, port, database name, user, password, and SSL options.
- Uses the
pg-promiselibrary internally to manage database connections and queries. - SSL configuration supports certificates and keys if required by the database server.
- No additional external services are needed beyond the PostgreSQL instance.
Troubleshooting
- Connection errors: Ensure the provided credentials and SSL settings are correct. Misconfigured SSL or wrong host/port will cause connection failures.
- Query syntax errors: Invalid SQL syntax or incorrect parameter usage will result in errors. Verify the query string and parameter placeholders match the provided query parameters.
- Large number precision: If numeric columns have more than 16 digits, set "Output Large-Format Numbers As" to "Text" to avoid incorrect values.
- Unsupported operation error: This node only supports "Execute Query", "Insert", and "Update" operations. Using other operations will throw an error.
- Transaction mode issues: When using "Transaction" mode, if one query fails, the entire transaction rolls back. Use "Continue on Fail" cautiously in this mode.
Links and References
- PostgreSQL Documentation — Reference for SQL syntax and features.
- n8n Docs: PostgreSQL Node — Official documentation with examples and advanced usage.
- pg-promise GitHub — Underlying library used for database interaction.