PostgreSQL Query Builder Helper¶
Interactive helper for exploring a PostgreSQL database and preparing queries. It can list tables in a schema, show columns for a table, suggest JOINs based on foreign key relationships, and provide baseline query-building guidance from a natural-language description. Results can be returned as text/JSON and optionally as HTML, XLSX, or PDF depending on the selected output format.
Usage¶
Use this node early in a workflow to understand your database structure before building full SQL. Typical flow: 1) discover_tables to list tables in a schema, 2) get_table_columns to inspect column details, 3) suggest_joins for relationship hints, 4) build_query to get high-level guidance from a description, then pass your findings to a query execution or visual query node to run the final SQL.
Inputs¶
| Field | Required | Type | Description | Example |
|---|---|---|---|---|
| credentials_path | True | STRING | Path or reference to stored PostgreSQL credentials compatible with the 'postgres' credential template. | /configs/credentials/postgres.json |
| timeout | True | INT | Maximum time in seconds to wait for the request to complete. | 60 |
| action | True | CHOICE | Operation to perform. Options: discover_tables, get_table_columns, suggest_joins, build_query. | discover_tables |
| target_schema | True | STRING | Schema to explore for tables and relationships. | public |
| table_name | False | STRING | Table name used for column discovery or join suggestions. Required for get_table_columns and suggest_joins. | users |
| query_requirements | False | STRING | Natural-language description of the data you want, used to provide basic query-building suggestions when action is build_query. | Find each user with their total number of orders in the last 30 days |
| output_format | True | CHOICE | Result format. Options: text, html, xlsx, pdf, all. | text |
Outputs¶
| Field | Type | Description | Example |
|---|---|---|---|
| text | STRING | Human-readable text summary of the action result (tables list, column info, join suggestions, or guidance). Empty for some formats. | Tables in Schema: public\n- users\n- orders\n... |
| json | STRING | JSON string containing the structured result or error details. | {"suggestions": ["JOIN orders ON users.id = orders.user_id"]} |
| html | HTML | HTML representation of the result when output_format is html. Otherwise empty. | Join Suggestions: public.usersJOIN orders ON users.id = orders.user_id |
| xlsx | XLSX | XLSX binary data of the result when output_format is xlsx. Otherwise empty. | |
| PDF binary data of the result when output_format is pdf. Otherwise empty. |
Important Notes¶
- Table name is required when action is get_table_columns or suggest_joins.
- discover_tables and get_table_columns rely on valid credentials and access to the target schema.
- suggest_joins inspects information_schema metadata to infer foreign key relationships; results depend on proper FK constraints in the database.
- build_query returns general patterns and suggestions; it does not generate executable SQL automatically.
- When output_format is html/xlsx/pdf, text may be empty and only the selected format plus JSON is returned.
- For 'all' output in this helper, text and JSON are returned; HTML/XLSX/PDF are empty for helper actions.
Troubleshooting¶
- Error: 'Table name is required for column discovery/join suggestions' — Provide a non-empty table_name when using get_table_columns or suggest_joins.
- No tables returned — Verify target_schema is correct and the credentials have sufficient privileges.
- No foreign key relationships found — Ensure FK constraints exist; otherwise, join suggestions may be empty.
- Timeout occurred — Increase the timeout value or narrow the scope (e.g., use a specific schema or table).
- Unexpected result format — Confirm output_format matches your desired output; switch to 'text' for quick summaries or 'html/xlsx/pdf' for formatted outputs.