PostgreSQL Query Builder Helper

Interactive helper for exploring a PostgreSQL database and scaffolding queries. It can list tables in a schema, inspect table columns, suggest JOINs based on foreign key relationships, and provide basic query-building guidance from a natural language description. Outputs can be returned as text/JSON and optionally as HTML, XLSX, or PDF summaries.

Usage

Use this node early in a workflow to understand the database structure before writing queries. Start with discover_tables to see what's available in a schema, then get_table_columns for details on a specific table. Use suggest_joins to identify likely JOIN conditions. If you're unsure how to approach a query, use build_query to get starter patterns and guidance. Pair the insights with downstream nodes that execute or visualize queries.

Inputs

Field	Required	Type	Description	Example
credentials_path	True	STRING	Path or reference to PostgreSQL credentials configured for the 'postgres' service.	/configs/credentials/postgres.json
timeout	True	INT	Request timeout (in seconds) for metadata lookups and helper actions.	60
action	True	CHOICE	Helper action to perform: discover schemas/tables, inspect columns, suggest joins, or build a query outline.	discover_tables
target_schema	True	STRING	Database schema to explore or use as the context for discovery and suggestions.	public
table_name	False	STRING	Specific table for column discovery or join suggestions. Required when action is get_table_columns or suggest_joins.	users
query_requirements	False	STRING	Natural language description of the data you want (used when action is build_query to provide starter patterns and guidance).	Find users with their latest order and total spend in the last 30 days
output_format	True	CHOICE	Choose how results are returned: text (text + JSON only), html (HTML summary), xlsx (Excel), pdf (PDF), or all (text + JSON; other formats may be empty for helper outputs).	text

Outputs

Field	Type	Description	Example
text	STRING	Human-readable summary of the requested helper action (tables list, columns, join suggestions, or query guidance).	Tables in Schema: public - users - orders - products
json	STRING	JSON-serialized payload of the helper result (e.g., lists of tables/columns or an array of suggested JOIN strings).	{"suggestions": ["JOIN orders ON users.id = orders.user_id"]}
html	STRING	HTML-formatted summary of the helper result when output_format is html.	Join Suggestions: public.users JOIN orders ON users.id = orders.user_id
xlsx	BYTES	Excel file bytes containing a simple tabular representation of the helper result when output_format is xlsx.
pdf	BYTES	PDF file bytes with a formatted report of the helper result when output_format is pdf.

Important Notes

• Action requirements: table_name is required for get_table_columns and suggest_joins.
• Schema context: target_schema defaults to public. Ensure it matches your data.
• Join suggestions: Derived from information_schema foreign key relationships and may not capture all logical joins.
• Build query: Provides generic SQL patterns and guidance; it does not execute a query. Use execution or visual query nodes to run SQL.
• Output population: Depending on output_format, only some outputs will be populated; others may be empty strings.
• Permissions: The provided credentials must have sufficient privileges to read information_schema and target tables.

Troubleshooting

• Empty results when discovering tables: Verify target_schema is correct and the user has permissions to list tables.
• No join suggestions returned: The table may not have foreign key relationships, or permissions to information_schema are limited.
• Column discovery errors: Ensure table_name is provided and spelled correctly, and that the table exists in target_schema.
• Timeouts: Increase the timeout input for large schemas or slow connections.
• Unexpected empty XLSX/PDF: For helper actions, only summary content is generated; choose text or html for richer on-screen results, or ensure output_format matches your needs.
• Authentication failures: Check credentials_path configuration, host accessibility, and that the credentials are valid for the 'postgres' service.