PostgreSQL come sorgente dati per le etichette: una query, migliaia di etichette

L'anagrafica articoli si trova in PostgreSQL e le etichette devono nascere da lì. La strada abituale è un export CSV che è già superato nel momento in cui termina. La strada migliore: il database resta la fonte, e la stampa delle etichette lo interroga direttamente.

Tutto ciò che è descritto qui vale anche per MySQL e MariaDB - cambia solo l'aspetto della stringa di connessione.

Due strade verso il database

Tramite l'agente, quando il database si trova nella tua rete. L'agente zplCloudCli apre una connessione in uscita verso la piattaforma, esegue la query in locale e restituisce solo le righe del risultato. La stringa di connessione resta esclusivamente sulla tua macchina. Non servono porte in ingresso.

Direttamente dal cloud, quando il database è comunque raggiungibile - per esempio un Azure Database for PostgreSQL o Amazon RDS. La piattaforma si collega allora da sola; la stringa di connessione viene salvata cifrata AES nel database della piattaforma e decifrata solo per eseguire la query.

Via agente: registrare il server

L'agente conosce i propri database tramite un'opzione, una variabile d'ambiente o un file. Le tre modalità sono equivalenti.

# come opzione di avvio
zplcloud proxy --agent "Warehouse" \
  --postgres WMS="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=...;SSL Mode=Require"

# oppure come variabile d'ambiente
export ZPLCLOUD_PG_WMS_CONNECTION="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..."
zplcloud proxy --agent "Warehouse"

# oppure come pgservers.json accanto al binario o in ~/.zplcloud/
# { "postgresServers": { "WMS": "Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..." } }

Il nome dopo l'opzione (WMS) è quello che compare poi nel selettore. Per MySQL l'opzione è --mysql, per MariaDB --mariadb, con variabili e file corrispondenti.

Un consiglio dalla pratica: crea un utente di database dedicato con diritti di sola lettura esattamente sulle tabelle che servono alle etichette. L'agente esegue sempre e solo SELECT, ma un account che non può fare di più è la garanzia più solida.

Creare la sorgente dati

In Data hub → Origini dati → Nuova scegli il tipo PostgreSQL (agente) o PostgreSQL (Cloud), poi l'agente e il server. Il campo query accetta una singola 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

Campi legge le colonne senza caricare dati - dopodiché sono disponibili nel designer come binding. Test verifica la connessione.

Cosa può contenere una query

Le regole sono volutamente rigide, perché una sorgente dati serve a leggere e non a scrivere:

• Solo una singola SELECT o WITH, niente punto e virgola, niente commenti, niente istruzioni multiple.
• I valori dei filtri arrivano al database sempre come parametri, mai come testo concatenato. Una SQL injection attraverso la riga dei filtri non è quindi possibile.
• Filtro, ordinamento e LIMIT/OFFSET vengono applicati dal database, non dalla piattaforma. I tuoi indici fanno il loro lavoro.
• Al massimo 1000 righe per recupero, timeout di 15 secondi.

Quelle 1000 righe non sono un limite per la stampa: per le stampe massive la piattaforma recupera lato server un blocco dopo l'altro, fino a 50.000 etichette in un'unica esecuzione. In memoria viene tenuto sempre un solo blocco.

Dove finiscono i dati

Una sorgente dati pronta è disponibile ovunque servano dati:

• Print View - un URL protetto con un modulo in cui qualcuno cerca per EAN e stampa l'etichetta restituita.
• Stampa batch - tutti i risultati di una query in una volta, inviati alla stampante a blocchi.
• Designer - come dati di binding, così l'anteprima mostra valori reali invece di segnaposto.

Errori comuni

• “The query must start with SELECT.” Basta un punto e virgola finale per provocare questo errore. Toglilo.
• Nessuna colonna trovata. Le colonne calcolate hanno bisogno di un nome: SELECT price 1.19 AS gross invece di SELECT price 1.19.
• La connessione non riesce. I server PostgreSQL raggiungibili di solito richiedono TLS: SSL Mode=Require va nella stringa di connessione.
• Agente non online. L'agente mantiene da solo la connessione. La panoramica degli agenti nel data hub mostra quali agenti sono presenti e quali server segnalano.