SQL Server come sorgente dati: il loop dell'export, eliminato

Il loop dell'export, e perché si rompe

I dati delle etichette vivono in un ERP, un WMS o un database Azure SQL. Il flusso abituale è esportare in CSV, sistemare i nomi delle colonne, caricare, stampare - e ripetere domani, perché il CSV è già obsoleto.

Il data hub zplCloud elimina l'export. Un agente CLI nella tua rete detiene la stringa di connessione SQL Server, la piattaforma gli invia una descrizione di query, e tornano solo le righe di risultato. Il database non viene mai esposto a internet e le credenziali non vengono mai memorizzate nel cloud.

Questo post è la meccanica esatta: cosa gira dove, quale SQL viene generato e quali sono i limiti duri.

Architettura in un paragrafo

zplcloud proxy apre una connessione TLS in uscita verso api.zplcloud.com (SignalR). Niente porta in ingresso, niente regola NAT, niente VPN. Quando apri una sorgente dati nella piattaforma, il backend invia all'agente un oggetto di richiesta - query di base, filtro, ordinamento, offset, limite - e l'agente lo trasforma in T-SQL, lo esegue contro il tuo SQL Server con il tuo utente di database, e restituisce le righe. La stringa di connessione esiste solo nella memoria del processo dell'agente e nella sua configurazione locale.

Passo 1 - avvia l'agente con uno o più server

# Sono ammessi più flag --sql; il NOME è ciò che scegli nella piattaforma.
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 senza mettere i segreti nella riga di comando (finirebbero nella cronologia della shell):

# Windows PowerShell - una variabile per server, nome in mezzo
$env:ZPLCLOUD_SQL_PROD_CONNECTION = "Server=127.0.0.1;Database=erp;User Id=zplcloud;Password=…;Encrypt=True;TrustServerCertificate=True"
zplcloud proxy --agent "Lager"

Il banner di avvio elenca cosa ha trovato: SQL servers: PROD, WAREHOUSE. L'autenticazione sulla piattaforma usa --api-key <key> o ZPLCLOUD_API_KEY.

Rendilo persistente per il funzionamento non presidiato:

• Windows: setx ZPLCLOUD_SQL_PROD_CONNECTION "…", oppure zplcloud proxy --agent "Lager" --service-install --api-key sk_zplcloud_…
• Linux/Raspberry Pi: stesso flag --service-install; scrive un'unità systemd zplcloud-agent.service con Restart=always
• File invece di env: sqlservers.json accanto al binario o in ~/.zplcloud/, forma { "sqlServers": { "PROD": "Server=…" } }
• Docker: ZPLCLOUD_SQL_PROD_CONNECTION in docker-compose.agent.yml

Note sulle stringhe di connessione che costano un'ora alla gente

• Encrypt=True;TrustServerCertificate=True è la coppia pragmatica per un server interno con certificato autofirmato. Togli TrustServerCertificate una volta che hai un certificato vero.
• Un'istanza con nome richiede Server=host\INSTANCE; una porta non standard è Server=host,1433 - virgola, non due punti.
• Usa un login SQL dedicato con SELECT esattamente sulle tabelle di cui hanno bisogno le etichette. L'agente esegue tutto come quell'utente, quindi il database è il confine dei permessi - non la piattaforma.

Passo 2 - crea la sorgente dati

In Origini dati l'agente in esecuzione appare sotto Remote SQL Server con un chip per nome configurato. Cliccando un chip si precompila il modulo.

Test esegue SELECT 1 e restituisce server · database. Campi legge i metadati delle colonne via SELECT TOP 1 * con CommandBehavior.SchemaOnly - recupera lo schema senza tirare i dati. Se una query molto annidata non restituisce schema, l'agente ritenta una volta con SingleRow.

Passo 3 - cosa esegue realmente l'agente

La tua query di base viene avvolta come subquery. Filtro, ordinamento e paginazione vengono aggiunti dall'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

Tre cose meritano di essere lette due volte:

1. I valori sono parametri, mai concatenazione di stringhe. Il costruttore di filtri emette @p0, @p1, … e lega i valori tramite SqlCommand.Parameters. Non c'è nessun punto in cui un valore inserito dall'utente diventa testo SQL.

2. La paginazione è nativa. limit 10 diventa FETCH NEXT 10 ROWS ONLY; SQL Server fa il lavoro e restituisce dieci righe sul filo, non un milione.

3. Il conteggio delle righe è una query separata. Quando chiedi il totale, l'agente esegue SELECT COUNT(*) FROM (<base>) AS ds con lo stesso WHERE e gli stessi parametri.

I limiti duri (dal codice sorgente dell'agente)

Se ti servono più di 1000 righe in una vista - stampa batch, un catalogo completo - la piattaforma pagina attraverso il set di risultati con un OFFSET crescente. Ogni pagina è la sua richiesta da 1000 righe contro il tuo server, quindi la memoria resta piatta indipendentemente dal totale.

Un timeout di 15 secondi è deliberato. Se la tua query di base non può rispondere in 15 secondi, appartiene a una vista indicizzata o a una tabella con l'indice giusto, non a una sorgente dati di etichette.

Passo 4 - usalo nel designer e nelle Print Views

• Designer → scheda Dati di prova → Origine dati: scegli la sorgente dati e premi Carica. I binding dei campi si renderizzano con righe reali invece del testo segnaposto, quindi vedi le lunghezze reali dei campi prima che qualcosa raggiunga una stampante.
• Print Views → configurazione → Origine dati (Data Hub): l'anteprima della vista e la sua stampa usano la query live. L'operatore vede dati correnti; nessuno ricarica un CSV.

Modalità di errore e cosa significano

Piano

Il data hub (sorgenti dati SQL Server e MongoDB tramite l'agente CLI) fa parte del piano Pro. Dettagli sulla pagina prezzi.

Correlati

• CLI zplCloud - comandi, installazione servizio, USB, watch folders
• Agente come contenitore Docker
• Cloud Integration / Connections