Skip to content
Nappai Documentation

SQL Executor

The SQL Executor component lets you run a SQL statement against a database and receive the results directly in your Nappai dashboard. It’s useful for quick data checks, reporting, or feeding data into other parts of your automation workflow.

How it Works

When you provide a database URL and a SQL query, the component connects to the database using LangChain’s SQLDatabase utility. It then creates a QuerySQLDataBaseTool that executes the query. The result is returned as a plain text message. If the query fails, you can choose to either see the error message or simply get the original query back (passthrough mode). You can also decide whether to include column names in the output and whether to append the error details to the result.

Inputs

  • Add Error: If checked, any error that occurs during execution will be appended to the result text so you can see what went wrong.
  • Database URL: The full connection string for the database you want to query (e.g., postgresql://user:pass@host:5432/dbname). This field is required.
  • Include Columns: When enabled, the output will list the column names along with the data rows.
  • Passthrough: If an error happens, the component will return the original query instead of throwing an exception. This can help keep a workflow running even when a query fails.
  • Query to run: The SQL statement you want to execute. This field is required.

Outputs

  • Text: A Message object containing the query result, an error message, or the original query if passthrough is enabled. This output can be used in subsequent components or displayed in the dashboard.

Usage Example

  1. Add the component to your workflow and give it a name like “Get Sales Data”.
  2. Enter the Database URL for your PostgreSQL or MySQL instance.
  3. Write a simple SELECT query in the “Query to run” field, e.g. 
    SELECT order_id, total_amount FROM orders WHERE order_date > '2024-01-01';
  4. Check “Include Columns” if you want the column names in the result.
  5. Run the workflow. The component will return the rows that match the query, or an error message if something goes wrong.

You can then feed the output into a table component, a chart, or another automation step.

  • SQL Query Builder – Helps you construct queries visually before passing them to the SQL Executor.
  • Database Connector – Stores and manages database credentials securely for use in multiple components.
  • Data Formatter – Allows you to transform the raw text output into JSON or CSV for downstream use.

Tips and Best Practices

  • Keep your queries short and focused; large result sets can slow down the dashboard.
  • Use parameterized queries when possible to avoid SQL injection risks.
  • Enable “Add Error” during development to see detailed error messages, then disable it in production for cleaner output.
  • If you need to run the same query repeatedly, consider caching the result in a temporary table or using a “Cache” component.

Security Considerations

  • Store database URLs and credentials in Nappai’s secure credential store, not in plain text.
  • Avoid running queries that modify data unless you’re certain of the impact; consider using a read‑only user account.
  • Be cautious with user‑supplied queries; validate or sanitize input to prevent accidental data leaks or destructive commands.