DB Connect

DB Connect

Tipo: db-connect  ·  Paquete: Database Activities v1.0.3  ·  Salida: ZoanDbSession

Abre una conexión a una base de datos y devuelve una sesión (ZoanDbSession) que comparten las demás actividades de base de datos. Es el punto de partida de cualquier trabajo con SQL.

Cómo funciona

Crea la conexión con el driver del motor indicado en provider y la abre con la connectionString. Tienes dos modos (ver el modelo de sesión):

• Con body: las actividades dentro heredan la conexión automáticamente (no configuras session), y la conexión se cierra sola al terminar el body, también si una actividad interna falla. En este modo la actividad no devuelve salida.
• Sin body: guarda la sesión en una variable de salida; pásala como session a las demás actividades y ciérrala con DB Close.

Lo que conviene saber:

• Motores y drivers: sqlserver usa Microsoft.Data.SqlClient, postgres usa Npgsql, mysql usa MySqlConnector (sirve también para MariaDB) y odbc usa el driver ODBC instalado en la máquina del robot. En expresiones también se aceptan los alias mssql, sql server, postgresql, pg y mariadb, sin distinguir mayúsculas.
• Tiempos de espera: la actividad no fija tiempos propios; rigen los del driver. Si necesitas otros, ajústalos en la cadena de conexión con las palabras clave de ese driver.
• Transacciones: la conexión trabaja en modo autocommit: cada sentencia se confirma al ejecutarse. Para que varias sentencias se apliquen todas o ninguna, envíalas juntas en un solo DB Execute con la sintaxis de transacción del motor, o usa un procedimiento almacenado.
• Anidamiento: si dentro de un body abres otro DB Connect con body, las actividades internas usan la conexión más cercana; al salir se recupera la anterior.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
provider	string	—	Motor de base de datos: sqlserver · postgres · mysql · odbc.
connectionString	string	—	Cadena de conexión ADO.NET del driver elegido (servidor, base de datos, usuario, contraseña y opciones). Admite expresiones, por ejemplo credential("db-ventas")["value"] (cadena guardada como credencial de un solo valor) o armada con campos: "Server=db01;Database=ventas;User Id=" + credential("db")["user"] + ";Password=" + credential("db")["password"]. Pasar credential("x") sin ["…"] no sirve: la cadena llegaría como [credential].

Parámetros opcionales

Ninguno.

Sub-flujos

body opcional

Actividades a ejecutar con esta conexión. Heredan la sesión sin configurar session y la conexión se cierra al salir. Si se omite (o queda vacío), la actividad devuelve la sesión como salida y debes cerrarla con DB Close.

Salida

• Sin body: un ZoanDbSession con la conexión abierta. Pásalo como session a DB Query, DB Execute, DB Scalar y DB Close.
• Con body: esta actividad no devuelve ningún valor; la sesión solo existe dentro del body.

Ejemplo

DB Connect   provider = sqlserver   connectionString = credential("db-ventas")["value"]
 └─ body:
      DB Query   sql = "SELECT TOP 10 Id, Nombre FROM Clientes ORDER BY FechaAlta DESC"   → output: clientes
      Log        message = "Clientes leídos: " + rowCount(clientes)

Con la sesión en una variable:

DB Connect   provider = postgres   connectionString = credential("db-reportes")["value"]   → output: db
DB Scalar    session = db   sql = "SELECT COUNT(*) FROM facturas WHERE pagada = false"   → output: pendientes
DB Close     session = db

Protege la cadena de conexión

La connectionString contiene la contraseña de la base de datos. Guárdala en una credencial y úsala con credential("db-ventas")["value"], nunca en texto plano. Ver cadena de conexión.

Errores comunes

Mensaje	Causa y solución
Proveedor '…' no admitido. Usa: sqlserver, postgres, mysql, odbc.	El valor de provider no es un motor conocido. Elige uno de la lista o un alias válido.
'provider' es obligatorio. / 'connectionString' es obligatorio.	Falta el parámetro o la expresión dio vacío (por ejemplo, una credencial inexistente).
Blocked expression: contains a disallowed pattern (credential extraction in expressions is not allowed — use credential() in a param of type 'credential': '.ToPlainText(')…	La expresión usa .ToPlainText(), que está bloqueado en las expresiones. Lee el valor con credential("x")["value"] o el campo que corresponda (["password"]).
Error del driver: inicio de sesión fallido, servidor inaccesible, base de datos inexistente, palabra clave no admitida	El mensaje viene del motor o del driver. Revisa servidor, puerto, usuario, contraseña, firewall y la sintaxis de la cadena para ese driver. Si la red es inestable, envuelve la conexión en un Retry.

Actividades relacionadas

• DB Query / DB Execute / DB Scalar — operar con la sesión.
• DB Close — cerrar la conexión (modo sin body).
• Try / Catch — manejar los errores de conexión.