Saltearse al contenido
Nappai Documentation

SQL Executor

El SQL Executor permite a los usuarios ejecutar consultas SQL directamente desde el panel de control de Nappai. Con solo proporcionar la URL de la base de datos y la consulta, el componente devuelve los resultados en un formato legible, con opciones para incluir los nombres de columna, manejar errores y controlar el comportamiento cuando algo falla.

¿Cómo funciona?

Cuando ingresas la URL de la base de datos y la consulta, el componente crea una conexión a la base de datos usando la librería SQLDatabase de LangChain. Luego, utiliza la herramienta QuerySQLDataBaseTool para ejecutar la consulta. Los resultados se devuelven como un mensaje de texto. Si ocurre un error, puedes elegir que el componente devuelva la propia consulta (modo passthrough) o que incluya el mensaje de error en la salida.

Entradas

  • Add Error: Si se activa, el mensaje de error se añadirá al resultado final, lo que facilita la depuración.
  • Database URL: La dirección completa (incluyendo usuario, contraseña y puerto) que permite conectar con la base de datos.
  • Include Columns: Cuando está activado, la respuesta incluirá los nombres de las columnas junto con los datos.
  • Passthrough: Si se produce un error, el componente devolverá la propia consulta en lugar de lanzar una excepción, lo que evita que el flujo se detenga.
  • Query to run: La sentencia SQL que deseas ejecutar. Debe ser válida y estar escrita en el dialecto de tu base de datos.

Salidas

  • Text: Un mensaje que contiene los resultados de la consulta. Si la consulta no devuelve filas, el mensaje será “Nothing found”. En caso de error, el mensaje puede incluir la consulta y el error, dependiendo de las opciones seleccionadas.

Ejemplo de Uso

  1. Conecta tu base de datos

    • En el campo Database URL escribe:
      postgresql://usuario:contraseña@mi-servidor:5432/mi_base_de_datos

  2. Define la consulta

    • En Query to run escribe: 
      SELECT nombre, email FROM clientes WHERE activo = true;

  3. Configura las opciones

    • Activa Include Columns si quieres ver los nombres de las columnas.
    • Deja Passthrough desactivado para que el flujo se detenga si algo falla.
    • Activa Add Error si quieres que el mensaje de error se muestre junto con los resultados.

  4. Ejecuta

    • El componente devuelve un mensaje con los datos solicitados. Si no hay resultados, verás “Nothing found”.

Componentes Relacionados

  • Database Connector – Establece la conexión inicial a la base de datos y gestiona credenciales de forma segura.
  • SQL Query Builder – Permite crear consultas SQL de forma visual antes de pasarlas al SQL Executor.

Consejos y Mejores Prácticas

  • Mantén tus credenciales seguras: Usa variables de entorno o el gestor de secretos de Nappai para almacenar la URL de la base de datos.
  • Prueba tus consultas en un entorno de desarrollo antes de ejecutarlas en producción.
  • Activa Passthrough solo en modo de depuración para evitar que errores inesperados detengan flujos críticos.
  • Incluye columnas solo cuando sea necesario; omitirlas reduce la cantidad de datos transferidos y mejora el rendimiento.

Consideraciones de Seguridad

  • La URL de la base de datos contiene credenciales sensibles. Asegúrate de que solo usuarios autorizados tengan acceso a este componente.
  • Evita exponer resultados que contengan información confidencial en flujos públicos.
  • Si la base de datos está expuesta a Internet, utiliza conexiones cifradas (SSL/TLS) y firewalls para limitar el acceso.