Skip to content
Nappai Documentation

SQL Executor

The SQL Executor component lets you run any SQL query against a database you specify. It connects to the database, executes the query, and returns the result as plain text. You can choose to include column names, handle errors gracefully, or add error details to the output.

How it Works

When you provide a Database URL and a Query to run, the component first creates a connection to the database using the SQLDatabase utility. It then uses the QuerySQLDataBaseTool to execute the query. The result is returned as a text string.
If the query fails, you can set Passthrough to true so the component returns the original query instead of throwing an error. If Add Error is enabled, the error message is appended to the result so you can see what went wrong.

Inputs

  • Add Error: Add the error to the result.
  • Database URL: The URL of the database.
  • Include Columns: Include columns in the result.
  • Passthrough: If an error occurs, return the query instead of raising an exception.
  • Query to run: Query to execute in the database.

Outputs

  • Text: The result of the SQL query or an error message, depending on the settings.

Usage Example

  1. Drag the SQL Executor component onto your workflow.
  2. Enter the Database URL (e.g., postgres://user:pass@host:5432/mydb).
  3. Write a simple query in Query to run such as SELECT * FROM customers LIMIT 10;.
  4. Set Include Columns to true if you want column names in the output.
  5. Run the workflow. The component will return the query results as text, which you can feed into a Data Formatter or display in a dashboard widget.
  • Database Connector – Establishes a connection to a database and provides connection details to other components.
  • Data Formatter – Converts raw text or JSON into tables, charts, or other visual formats.
  • Error Logger – Captures and stores error messages for later review.

Tips and Best Practices

  • Keep your database credentials secure; store them in environment variables or a secrets manager.
  • Use parameterized queries or prepared statements to avoid SQL injection.
  • Test queries in a safe environment before running them in production.
  • Enable Add Error only when you need detailed debugging information; otherwise, keep it off to avoid leaking sensitive data.
  • If you need to run the same query on multiple databases, use the Passthrough option to quickly see which query failed.

Security Considerations

  • The component accepts raw SQL, so any user with access can execute arbitrary commands. Restrict access to trusted users only.
  • Avoid exposing the Database URL in public dashboards; use secure storage.
  • Be cautious with Passthrough mode; it can reveal the query text to downstream components, which might expose sensitive information.
  • Regularly audit database permissions to ensure the account used by the component has only the necessary privileges.