Saltearse al contenido
Nappai Documentation

libSQL

Este componente actúa como la puerta de entrada principal para trabajar con bases de datos libSQL y Turso dentro de tu flujo de automatización. Su objetivo es simplificarte la conexión y ejecución de consultas, eliminando la necesidad de escribir código complejo o gestionar credenciales manualmente. Gracias a su diseño intuitivo, puedes enfocarte en los datos que necesitas obtener o modificar sin preocuparte por la infraestructura técnica subyacente.

¿Cómo funciona?

Internamente, este nodo funciona como un puente seguro entre tu flujo de Nappai y tu base de datos. Cuando ejecutas el componente, el sistema:

  1. Autentica la conexión utilizando la credencial que seleccionas en el panel.
  2. Valida y prepara tu consulta o filtros para asegurar que se ejecuten correctamente y de forma segura.
  3. Ejecuta la operación en la base de datos (ya sea una lectura, actualización o inserción).
  4. Devuelve los resultados de manera estructurada, lista para ser usada en los siguientes pasos de tu flujo.

No es necesario configurar servidores, manejar claves de API directamente en el código ni gestionar conexiones manuales. El componente se encarga automáticamente de todo el proceso de validación, ejecución y retorno de datos, manteniendo una interfaz limpia y predecible para el dashboard gráfico.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con el servicio externo:

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo libSQL / Turso y guarda los campos requeridos (URL del servidor y Token de seguridad).
  3. En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Entradas

Los siguientes campos están disponibles para configurar este componente:

  • Operation: Selecciona la operación principal de libSQL que deseas realizar.
  • Number of Results: Especifica cuántos registros deseas recuperar en total.
  • Return All: Indica si deseas obtener todos los resultados disponibles o solo hasta un límite establecido.
  • Table Name: Selecciona la tabla de la base de datos donde se realizará la operación.
  • Custom Query: Escribe tu consulta SQL aquí. Puedes usar sentencias como SELECT, UPDATE, INSERT o DELETE. Es compatible con múltiples líneas para consultas más complejas.
  • Select Filter Type: Elige cómo construir tus condiciones de búsqueda. El modo String está recomendado para filtros simples (escribe condiciones estilo SQL natural). El modo Build Manually ofrece un constructor visual para condiciones avanzadas o múltiples filtros.
  • Filter String: Define las condiciones de búsqueda. Ejemplos: age > 25, name = 'Anna' AND city = 'Madrid'. Reglas clave: el texto va entre comillas simples, los números sin comillas, los booleanos en minúsculas y usa AND / OR en mayúsculas para unir condiciones. Si se deja vacío, se devuelven todos los registros.
  • Limit: Establece el número máximo de resultados a devolver.
  • Filters: Define cuántas condiciones de filtro se aplicarán para decidir qué filas recuperar.
  • Field to Update: Especifica cuántos campos de registro deseas modificar.
  • Mode: Selecciona cómo insertar datos: Dynamic (usa automáticamente las columnas de la tabla) o Custom (usa datos de ingestación personalizados).
  • Ingest Data: Proporciona los datos que deseas insertar en la tabla seleccionada.

Salidas

Después de ejecutar el nodo, recibirás la siguiente información para continuar en tu flujo:

  • Data: El conjunto de registros o resultados obtenidos tras ejecutar la consulta. Ideal para alimentar reportes, tablas dinámicas o envíos de notificaciones.
  • Database Info: Metadatos y detalles de configuración sobre la conexión actual con la base de datos. Útil para auditorías, verificación de estado o depuración de flujos.

Ejemplo de Respuesta JSONjson

{ “Data”: [ { “id”: 101, “name”: “Carlos Ruiz”, “city”: “Sevilla”, “status”: “active” }, { “id”: 102, “name”: “Laura Méndez”, “city”: “Bilbao”, “status”: “pending” } ], “Database Info”: { “engine”: “libSQL / Turso”, “connection_status”: “active”, “table_name”: “customers”, “last_sync”: “2024-06-15T10:30:00Z” } }

Conectividad

Este nodo se conecta de forma lógica con elementos posteriores en tus flujos de automatización:

  • El campo Data suele enlazarse con transformadores de datos, procesadores de textos, generadores de reportes o nodos de envío (correo, Slack, bases de datos destino).
  • El campo Database Info se utiliza típicamente en nodos de verificación de estado, registros de auditoría o para alimentar dashboards de monitorización.
  • Su diseño permite cadenas de automatización fluidas: una lectura o actualización realizada aquí puede alimentar inmediatamente filtros, cálculos o acciones de notificación sin interrupciones.

Ejemplo de Uso

Escenario: Necesitas extraer a todos los clientes mayores de 25 años de la tabla Usuarios, actualizar su estado a VIP y enviar una lista de nombres por correo.

  1. Selecciona la credencial Turso_Dev en el campo de credencial.
  2. En Table Name, elige Usuarios.
  3. En Select Filter Type, elige String Mode y en Filter String escribe age > 25.
  4. En Operation, selecciona Read & Filter (o la operación equivalente de tu flujo).
  5. Conecta la salida Data al nodo de procesamiento de correos. El sistema devolverá los registros filtrados, los cuales podrás mapear directamente en los campos de destinatarios y cuerpo del mensaje, completando el flujo en segundos.

Consejos y Mejores Prácticas

  • Utiliza el modo Filter String siempre que sea posible para consultas simples; es más rápido y reduce errores de sintaxis.
  • Mantén el campo Limit con valores razonables (ej. 50–500) cuando trabajes con tablas grandes para evitar ralentizaciones en el dashboard.
  • Activa Return All únicamente cuando necesites un listado completo y sepas que la tabla no excede el límite seguro de tu plan.
  • Verifica el campo Database Info al final de flujos críticos para confirmar que la conexión se mantuvo activa durante toda la ejecución.

Consideraciones de Seguridad

  • Nunca compartas o escribas manualmente los tokens o URLs de conexión; siempre utiliza el selector de Credential para garantizar que las claves se almacenen cifradas en Nappai.
  • El componente ya incluye protección automática contra inyecciones SQL y validación de esquemas, pero evita escribir condiciones en Filter String con inputs directamente sin validarlos previamente.
  • Revisa los permisos de tu cuenta en Turso/libSQL: otorga solo las capacidades necesarias (lectura, escritura o ambas) según el rol de cada flujo.
  • Monitorea el campo Database Info para detectar desconexiones temporales o cambios de estructura en las tablas antes de ejecutar automatizaciones recurrentes.