PostgreSQL como fuente de datos de etiquetas: una consulta, miles de etiquetas

Los datos maestros de artículos están en PostgreSQL y las etiquetas deben salir de ahí. El camino habitual es una exportación CSV que ya está desactualizada en el momento en que termina. El camino mejor: la base de datos sigue siendo la fuente y la impresión de etiquetas la consulta directamente.

Todo lo descrito aquí se aplica también a MySQL y MariaDB - solo cambia el aspecto de la cadena de conexión.

Dos caminos hacia la base de datos

A través del agente, cuando la base de datos está dentro de tu propia red. El agente zplCloudCli abre una conexión saliente con la plataforma, ejecuta la consulta en local y devuelve solo las filas de resultado. La cadena de conexión solo existe en tu máquina. No hacen falta puertos de entrada.

Directamente desde la nube, cuando la base de datos es accesible de todos modos - por ejemplo, Azure Database for PostgreSQL o Amazon RDS. En ese caso la plataforma se conecta por sí misma; la cadena de conexión se almacena cifrada con AES en la base de datos de la plataforma y solo se descifra para ejecutar la consulta.

Ruta del agente: registrar el servidor

El agente conoce sus bases de datos mediante una opción, una variable de entorno o un archivo. Las tres formas son equivalentes.

# como opción de arranque
zplcloud proxy --agent "Warehouse" \
  --postgres WMS="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=...;SSL Mode=Require"

# o como variable de entorno
export ZPLCLOUD_PG_WMS_CONNECTION="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..."
zplcloud proxy --agent "Warehouse"

# o como pgservers.json junto al binario o en ~/.zplcloud/
# { "postgresServers": { "WMS": "Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..." } }

El nombre que sigue a la opción (WMS) es el que aparece después en el selector. Para MySQL la opción es --mysql y para MariaDB --mariadb, con las variables y los archivos correspondientes.

Un consejo de la práctica: crea un usuario de base de datos dedicado con permisos de solo lectura exactamente sobre las tablas que necesitan las etiquetas. El agente solo ejecuta SELECT, pero una cuenta que no puede hacer más es la garantía más sólida.

Crear la fuente de datos

En Data hub → Fuentes de datos → Nueva elige el tipo PostgreSQL (agente) o PostgreSQL (Cloud) y, a continuación, el agente y el servidor. El campo de consulta admite un único SELECT:

SELECT a.sku, a.description, a.ean, s.bin, a.best_before
FROM article a
JOIN stock s ON s.article_id = a.id
WHERE a.active = true

Campos lee las columnas sin cargar datos; después están disponibles en el diseñador como vinculaciones. Probar comprueba la conexión.

Qué puede contener una consulta

Las reglas son deliberadamente estrictas, porque una fuente de datos está para leer y no para escribir:

• Solo un único SELECT o WITH, sin punto y coma, sin comentarios, sin varias sentencias.
• Los valores de filtro llegan siempre a la base de datos como parámetros, nunca como texto concatenado. Por eso no es posible una inyección SQL a través de la fila de filtro.
• El filtro, la ordenación y LIMIT/OFFSET los aplica la base de datos, no la plataforma. Tus índices hacen su trabajo.
• Como máximo 1000 filas por lectura y 15 segundos de tiempo de espera.

Esas 1000 filas no son un límite para imprimir: en las tiradas masivas la plataforma obtiene en el servidor un bloque tras otro, hasta 50.000 etiquetas de una vez. En memoria solo se mantiene un bloque cada vez.

Dónde terminan los datos

Una fuente de datos terminada está disponible en todos los lugares donde se necesitan datos:

• Vistas de impresión - una URL protegida con un formulario en el que alguien busca por EAN e imprime la etiqueta resultante.
• Impresión por lotes - todos los resultados de una consulta a la vez, enviados a la impresora por bloques.
• Diseñador - como datos de vinculación, para que la vista previa muestre valores reales en lugar de marcadores de posición.

Errores frecuentes

• «The query must start with SELECT.» Basta con un punto y coma al final para provocarlo. Quítalo.
• No se encuentran columnas. Las columnas calculadas necesitan un nombre: SELECT price 1.19 AS gross en lugar de SELECT price 1.19.
• La conexión falla. Los servidores PostgreSQL accesibles suelen exigir TLS: SSL Mode=Require debe ir en la cadena de conexión.
• El agente no está en línea. El agente mantiene la conexión por sí mismo. La vista general de agentes del data hub muestra cuáles están presentes y qué servidores notifican.