SQL Server como fuente de datos: el bucle del export, eliminado

El bucle del export, y por qué se rompe

Los datos de las etiquetas viven en un ERP, un WMS o una base de datos Azure SQL. El flujo habitual es exportar a CSV, arreglar los nombres de columna, subir, imprimir - y repetirlo mañana, porque el CSV ya está obsoleto.

El data hub de zplCloud elimina el export. Un agente CLI dentro de tu red guarda la cadena de conexión de SQL Server, la plataforma le envía una descripción de consulta, y solo vuelven las filas de resultado. La base de datos nunca se expone a internet y las credenciales nunca se almacenan en la nube.

Este post es la mecánica exacta: qué se ejecuta dónde, qué SQL se genera y cuáles son los límites duros.

Arquitectura en un párrafo

zplcloud proxy abre una conexión TLS saliente con api.zplcloud.com (SignalR). Sin puerto de entrada, sin regla NAT, sin VPN. Cuando abres una fuente de datos en la plataforma, el backend envía al agente un objeto de solicitud - consulta base, filtro, ordenación, offset, límite - y el agente lo convierte en T-SQL, lo ejecuta contra tu SQL Server con tu usuario de base de datos, y devuelve las filas. La cadena de conexión existe solo en la memoria del proceso del agente y en su configuración local.

Paso 1 - inicia el agente con uno o más servidores

# Se permiten varias banderas --sql; el NOMBRE es lo que eliges en la plataforma.
zplcloud proxy --agent "Lager" \
  --sql PROD="Server=127.0.0.1;Database=erp;User Id=zplcloud;Password=…;Encrypt=True;TrustServerCertificate=True" \
  --sql WAREHOUSE="Server=sql-wh.internal.lan,1433;Database=logistik;User Id=zplcloud;Password=…;Encrypt=True;TrustServerCertificate=True"

Equivalente sin poner secretos en la línea de comandos (acabarían en tu historial del shell):

# Windows PowerShell - una variable por servidor, nombre en el medio
$env:ZPLCLOUD_SQL_PROD_CONNECTION = "Server=127.0.0.1;Database=erp;User Id=zplcloud;Password=…;Encrypt=True;TrustServerCertificate=True"
zplcloud proxy --agent "Lager"

El banner de inicio lista lo encontrado: SQL servers: PROD, WAREHOUSE. La autenticación contra la plataforma usa --api-key <key> o ZPLCLOUD_API_KEY.

Hazlo persistente para operación desatendida:

• Windows: setx ZPLCLOUD_SQL_PROD_CONNECTION "…", o zplcloud proxy --agent "Lager" --service-install --api-key sk_zplcloud_…
• Linux/Raspberry Pi: misma bandera --service-install; escribe una unidad systemd zplcloud-agent.service con Restart=always
• Archivo en vez de env: sqlservers.json junto al binario o en ~/.zplcloud/, forma { "sqlServers": { "PROD": "Server=…" } }
• Docker: ZPLCLOUD_SQL_PROD_CONNECTION en docker-compose.agent.yml

Notas sobre cadenas de conexión que cuestan una hora a la gente

• Encrypt=True;TrustServerCertificate=True es la pareja pragmática para un servidor interno con certificado autofirmado. Quita TrustServerCertificate cuando tengas un certificado real.
• Una instancia con nombre necesita Server=host\INSTANCE; un puerto no estándar es Server=host,1433 - coma, no dos puntos.
• Usa un login SQL dedicado con SELECT exactamente sobre las tablas que necesitan las etiquetas. El agente ejecuta todo como ese usuario, así que la base de datos es la frontera de permisos - no la plataforma.

Paso 2 - crea la fuente de datos

En Fuentes de datos el agente en ejecución aparece bajo Remote SQL Server con un chip por nombre configurado. Al hacer clic en un chip se rellena el formulario.

Probar ejecuta SELECT 1 y devuelve servidor · base de datos. Campos lee los metadatos de columna vía SELECT TOP 1 * con CommandBehavior.SchemaOnly - obtiene el esquema sin traer datos. Si una consulta muy anidada no devuelve esquema, el agente reintenta una vez con SingleRow.

Paso 3 - qué ejecuta realmente el agente

Tu consulta base se envuelve como subconsulta. El filtro, la ordenación y la paginación los añade el agente:

SELECT * FROM ( SELECT ean, name, price FROM artikel ) AS ds
WHERE ean LIKE @p0
ORDER BY name
OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY

Tres cosas merecen leerse dos veces:

1. Los valores son parámetros, nunca concatenación de cadenas. El constructor de filtros emite @p0, @p1, … y vincula los valores a través de SqlCommand.Parameters. No hay ningún lugar donde un valor introducido por el usuario se convierta en texto SQL.

2. La paginación es nativa. limit 10 se convierte en FETCH NEXT 10 ROWS ONLY; SQL Server hace el trabajo y devuelve diez filas por la red, no un millón.

3. El recuento de filas es una consulta separada. Cuando pides el total, el agente ejecuta SELECT COUNT(*) FROM (<base>) AS ds con el mismo WHERE y los mismos parámetros.

Los límites duros (del código fuente del agente)

Si necesitas más de 1000 filas en una vista - impresión por lotes, un catálogo completo - la plataforma pagina a través del conjunto de resultados con OFFSET creciente. Cada página es su propia solicitud de 1000 filas contra tu servidor, así que la memoria se mantiene plana independientemente del total.

Un timeout de 15 segundos es deliberado. Si tu consulta base no puede responder en 15 segundos, pertenece a una vista indexada o a una tabla con el índice correcto, no a una fuente de datos de etiquetas.

Paso 4 - úsalo en el diseñador y en Print Views

• Diseñador → pestaña Datos de prueba → Fuente de datos: elige la fuente de datos y pulsa Cargar. Los bindings de campo se renderizan con filas reales en lugar de texto de marcador de posición, así que ves las longitudes reales de campo antes de que nada llegue a una impresora.
• Print Views → configuración → Fuente de datos (Data Hub): la vista previa de la vista y su impresión usan la consulta en vivo. El operador ve datos actuales; nadie vuelve a subir un CSV.

Modos de fallo y qué significan

Plan

El data hub (fuentes de datos SQL Server y MongoDB a través del agente CLI) es parte del plan Pro. Detalles en la página de precios.

Relacionado

• CLI de zplCloud - comandos, instalación de servicio, USB, watch folders
• Agente como contenedor Docker
• Cloud Integration / Connections