DB Execute

DB Execute

Tipo: db-execute  ·  Paquete: Database Activities v1.0.3  ·  Salida: int

Ejecuta una sentencia que modifica datos —INSERT, UPDATE o DELETE— y devuelve el número de filas afectadas. Es la actividad de escritura en la base de datos: insertar registros, actualizar estados, borrar datos.

Cómo funciona

Ejecuta la sentencia sobre la conexión y devuelve cuántas filas cambió. Usa parámetros @nombre y el campo params para los valores variables (ver consultas parametrizadas).

• Sesión: si no indicas session, usa la del body de DB Connect que la contiene.
• Parámetros: cada clave de params se envía como @clave (con o sin @). Con odbc, los @nombre se cambian por ? en orden de aparición y un nombre sin valor se envía como NULL.
• Confirmación inmediata: no hay una transacción abierta por el paquete; cada sentencia queda confirmada al terminar. Si necesitas que varias se apliquen todas o ninguna, envíalas en un mismo sql dentro de la transacción del motor (por ejemplo BEGIN TRAN … COMMIT en SQL Server) o usa un procedimiento almacenado.
• Otras sentencias: también sirve para procedimientos almacenados (EXEC/CALL) y sentencias de definición (CREATE, ALTER); en ese caso el conteo depende de lo que informe el motor.
• Reintentos: un INSERT repetido crea filas duplicadas. Si lo envuelves en un Retry, escribe la sentencia para que repetirla no duplique datos (por ejemplo, comprobando antes si el registro existe).

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
sql	string	—	La sentencia INSERT, UPDATE o DELETE. Usa @nombre para los valores variables. Admite varias líneas y expresiones.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
session	ZoanDbSession	—	Sesión de DB Connect. Dentro de un body se hereda automáticamente; fuera, pasa db.
params	Dictionary	—	Valores de los parámetros, como objeto { "nombre": valor }. Los valores pueden ser expresiones; textos, números, true/false y null se envían con su tipo.

Salida

Devuelve un int con el número de filas afectadas: 0 si la condición no coincidió con ninguna fila. Con varias sentencias en el mismo sql, el valor suma lo que informa el motor. Si el motor no informa un conteo (sentencias de definición, SET NOCOUNT ON en SQL Server), el valor es -1.

Ejemplo

Marcar un pedido como despachado:

DB Execute
  sql    = "UPDATE Pedidos SET Estado = @estado WHERE Id = @id"
  params = { "estado": "despachado", "id": pedidoId }
  → output: filasAfectadas

If   condition = filasAfectadas == 0
 └─ then:
      Log   level = warning   message = "Ningún pedido con id " + pedidoId

Usa parámetros, no concatenación

Igual que en DB Query: pasa los valores con params, nunca concatenados en el SQL. Protege contra errores e inyección SQL.

Errores comunes

Mensaje	Causa y solución
'session' es obligatorio y debe ser una sesión de base de datos.	No hay sesión: la actividad está fuera de un body de DB Connect y no recibió session.
'sql' es obligatorio.	Falta la sentencia o la expresión dio vacío.
Error del motor: clave duplicada, restricción violada, columna inexistente, parámetro sin declarar	El mensaje viene de la base de datos. Revisa los datos y que cada @nombre tenga su clave en params. Captúralo con Try / Catch para registrar el caso y seguir.
Error del motor por tiempo de espera o bloqueo	La sentencia tardó más que el tiempo del driver o esperó un bloqueo. Acota el WHERE, divide la operación en lotes o reintenta con Retry.

Actividades relacionadas

• DB Query — leer datos con SELECT.
• DB Scalar — leer un único valor.