Database Activities

Versión: 1.0.3  ·  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")["value"]
 └─ 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")["value"]   → 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 instalado en la máquina del robot

En expresiones también se aceptan los alias mssql, sql server, postgresql, pg y mariadb. Cada motor usa su driver .NET (Microsoft.Data.SqlClient, Npgsql, MySqlConnector); para odbc el driver lo instalas tú en la máquina del robot.

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")["value"].

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.

Cómo se envían los parámetros

• Cada clave de params se envía como @clave; puedes escribir la clave con o sin @.
• Los valores pueden ser expresiones (clienteId); textos, números, true/false y null llegan al motor con su tipo.
• Con odbc, el paquete cambia cada @nombre del SQL por ? en el orden en que aparece: un nombre repetido envía su valor otra vez y un nombre sin valor en params se envía como NULL. Evita escribir @ dentro de textos literales del SQL cuando uses ODBC.
• Los parámetros sirven para valores, no para nombres de tabla o columna. Si un nombre de tabla viene de una variable, valídalo contra una lista de valores permitidos antes de armar el SQL.

Transacciones y tiempos de espera

• Autocommit: cada sentencia se confirma al ejecutarse; el paquete no abre transacciones. Para que varias sentencias se apliquen todas o ninguna, envíalas en un mismo DB Execute dentro de la transacción del motor (BEGIN TRAN … COMMIT en SQL Server, BEGIN; … COMMIT; en PostgreSQL) o usa un procedimiento almacenado.
• Tiempos de espera: las actividades no tienen un parámetro de timeout; rigen los del driver. Ajústalos en la cadena de conexión con las palabras clave del driver si lo necesitas.
• Errores: los errores del motor (sintaxis, restricciones, bloqueos, conexión) llegan con el mensaje original de la base de datos. Combínalos con Try / Catch y Retry.

Tres formas de consultar

Actividad	Para qué	Devuelve
DB Query	SELECT que devuelve varias filas	DataTable (0 filas si no hay coincidencias)
DB Scalar	SELECT que devuelve un solo valor (un COUNT, un MAX)	el valor (null si no hay filas)
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")["value"]
 └─ 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.