Saltearse al contenido
Nappai Documentation

SQL Executor

El componente SQL Executor te permite ejecutar consultas SQL directamente desde el dashboard de Nappai. Solo necesitas proporcionar la URL de la base de datos y la consulta que quieres ejecutar, y el componente te devuelve los datos que obtuviste.

¿Cómo funciona?

El componente se basa en la librería langchain. Cuando lo activas, se crea una conexión a la base de datos usando la URL que le indiques. Luego, con la herramienta QuerySQLDataBaseTool, se envía la consulta SQL y se recuperan los resultados.

  • Si la consulta se ejecuta correctamente, el resultado se devuelve como texto.
  • Si ocurre un error y la opción Passthrough está activada, en lugar de lanzar una excepción el componente devuelve la propia consulta SQL.
  • Si la opción Add Error está activada, el mensaje de error se añade al final del resultado, lo que facilita la depuración.

Entradas

Campos de Entrada

  • Add Error: Si se activa, el resultado incluirá información sobre cualquier error que ocurra, lo que facilita la depuración.
  • Database URL: La dirección completa de la base de datos (por ejemplo, postgres://user:pass@host:port/db). Es obligatorio.
  • Include Columns: Si se marca, el resultado mostrará los nombres de las columnas junto con los datos.
  • Passthrough: Si se activa y ocurre un error, en lugar de lanzar una excepción, el componente devuelve la propia consulta SQL. Útil para flujos que deben continuar sin detenerse.
  • Query to run: La sentencia SQL que quieres ejecutar. Obligatorio.

Salidas

  • Text: El resultado de la consulta en formato de texto. Si hay error y Add Error está activado, el texto incluirá el mensaje de error y la consulta.

Ejemplo de Uso

Supongamos que quieres obtener los últimos 10 registros de la tabla orders:

  1. Database URL: postgres://user:pass@db.example.com:5432/mydb
  2. Query to run: 
    SELECT * FROM orders ORDER BY created_at DESC LIMIT 10;
  3. Include Columns: True
  4. Passthrough: False
  5. Add Error: False

El componente devolverá una tabla con los datos solicitados.

Si la consulta contiene un error y activas Passthrough, el componente devolverá la propia consulta en lugar de lanzar una excepción, lo que permite que el flujo continúe sin interrupciones.

Componentes Relacionados

  • Database Connector – Conecta Nappai a distintas bases de datos.
  • SQL Query Builder – Crea consultas SQL de forma visual antes de pasarlas al SQL Executor.

Consejos y Mejores Prácticas

  • Usa consultas parametrizadas para evitar inyecciones SQL.
  • Mantén las credenciales seguras: almacénalas en variables de entorno o en el gestor de secretos de Nappai.
  • Prueba tus consultas en un entorno de desarrollo antes de ejecutarlas en producción.
  • Activa Include Columns cuando necesites depurar la estructura de los resultados.
  • Utiliza Passthrough solo cuando quieras que el flujo siga sin detenerse ante errores.

Consideraciones de Seguridad

  • Control de acceso: limita quién puede configurar la URL de la base de datos y ejecutar consultas.
  • Principio de menor privilegio: la cuenta de la base de datos usada por el componente debe tener solo los permisos necesarios.
  • Registro de auditoría: habilita logs de consultas para poder rastrear quién ejecutó qué y cuándo.
  • Validación de entrada: si la consulta proviene de usuarios, valida y sanitiza los parámetros para evitar ataques de inyección.