Database Activities

Versión: 1.0.0  ·  ID: zoan-packages-database  ·  Autor: Zoan Software

El paquete Database permite que tu automatización lea y modifique bases de datos directamente con SQL. Es la forma más eficiente de trabajar con grandes volúmenes de datos cuando tienes acceso a la base: consultar miles de registros, insertar resultados, actualizar estados. Soporta SQL Server, PostgreSQL, MySQL y cualquier fuente vía ODBC.

¿Necesito saber SQL?

Sí, un poco. Estas actividades ejecutan sentencias SQL que tú escribes (SELECT, INSERT, UPDATE, DELETE). No necesitas ser experto, pero sí conocer la consulta que quieres ejecutar. Si no tienes acceso a la base de datos, considera integrarte por su API o por su interfaz de escritorio/web.

El modelo: conectar → consultar → cerrar

Trabajar con una base de datos sigue el patrón abrir → usar → cerrar:

1. DB Connect abre una conexión y devuelve una sesión (ZoanDbSession).
2. Ejecutas una o varias consultas con DB Query, DB Execute o DB Scalar.
3. DB Close cierra la conexión.

Como en otros paquetes con sesión, hay dos formas:

Opción A — DB Connect con body (recomendada)

Las actividades dentro del body heredan la conexión automáticamente (no configuras session), y la conexión se cierra sola al terminar.

DB Connect   provider = sqlserver   connectionString = = credential("db-ventas").ToPlainText()
 └─ body:
      DB Query   sql = "SELECT * FROM Clientes WHERE Activo = 1"   → output: clientes
      DB Execute sql = "UPDATE Procesos SET UltimaCorrida = GETDATE()"

Opción B — Sesión en una variable

DB Connect guarda la sesión en una variable; cada actividad la recibe en session, y cierras con DB Close.

DB Connect   provider = postgres   connectionString = = credential("db").ToPlainText()   → output: db
DB Query   session = = db   sql = "SELECT * FROM pedidos"   → output: pedidos
DB Close   session = = db

Proveedores y cadena de conexión

provider	Motor
sqlserver	Microsoft SQL Server
postgres	PostgreSQL
mysql	MySQL / MariaDB
odbc	Cualquier fuente con driver ODBC

La cadena de conexión (connectionString) es el texto estándar de ADO.NET que indica servidor, base de datos y credenciales:

Server=db.empresa.com;Database=ventas;User Id=bot;Password=...;

La cadena de conexión lleva la contraseña: protégela

La cadena de conexión contiene credenciales. No la escribas en texto plano en el playbook. Guárdala completa en una credencial y úsala con = credential("db-ventas").ToPlainText().

Consultas parametrizadas: @nombre + params

Nunca metas valores de variables directamente en el texto SQL concatenando. En su lugar, usa parámetros: pon @nombre en la consulta y pasa los valores en el campo params (un objeto { nombre: valor }).

DB Query
  sql    = "SELECT * FROM Clientes WHERE Ciudad = @ciudad AND Activo = @activo"
  params = { "ciudad": = ciudadBuscada, "activo": true }
  → output: resultado

Seguridad: evita la inyección SQL

Concatenar valores en el SQL ("... WHERE Nombre = '" + nombre + "'") es peligroso: un dato con comillas puede romper la consulta o, peor, permitir un ataque de inyección SQL. Los parámetros @nombre evitan esto por completo y además manejan bien las comillas, fechas y nulos. Úsalos siempre que un valor venga de una variable.

Tres formas de consultar

Actividad	Para qué	Devuelve
DB Query	SELECT que devuelve varias filas	DataTable
DB Scalar	SELECT que devuelve un solo valor (un COUNT, un MAX)	el valor
DB Execute	INSERT / UPDATE / DELETE	nº de filas afectadas

Actividades

Actividad	Tipo	Salida	Qué hace
DB Connect	db-connect	ZoanDbSession	Abre una conexión y devuelve una sesión
DB Query	db-query	DataTable	Ejecuta un SELECT y devuelve las filas
DB Scalar	db-scalar	object	Ejecuta un SELECT y devuelve un único valor
DB Execute	db-execute	int	Ejecuta INSERT/UPDATE/DELETE; devuelve filas afectadas
DB Close	db-close	—	Cierra la conexión

Un flujo típico

Leer pedidos pendientes y marcarlos como procesados:

DB Connect   provider = sqlserver   connectionString = = credential("db-erp").ToPlainText()
 └─ body:
      DB Query   sql = "SELECT * FROM Pedidos WHERE Estado = @e"   params = { "e": "pendiente" }   → output: pedidos
      For Each   items = = pedidos   itemVariable = fila
       └─ activities:
            ... procesar ...
            DB Execute   sql = "UPDATE Pedidos SET Estado = 'procesado' WHERE Id = @id"   params = { "id": = fila["Id"] }

Siguientes pasos

• DB Connect — abrir la conexión.
• DB Query — la consulta más común.
• DataTable — procesar los resultados de un SELECT.