Lokalen SQL Server per zplCloud-CLI als Label-Datenquelle anbinden

Die Export-Schleife, und warum sie kaputtgeht

Labeldaten liegen im ERP, im WMS oder in einer Azure-SQL-Datenbank. Der übliche Ablauf: nach CSV exportieren, Spaltennamen geraderücken, hochladen, drucken - und morgen wieder, weil die CSV schon veraltet ist.

Der zplCloud-Datenhub schafft den Export ab. Ein CLI-Agent in deinem Netz hält den SQL-Server-Connection-String, die Plattform schickt ihm eine Abfragebeschreibung, und zurück kommen nur die Ergebniszeilen. Die Datenbank ist nie aus dem Internet erreichbar, die Zugangsdaten liegen nie in der Cloud.

Dieser Beitrag beschreibt die Mechanik: was wo läuft, welches SQL erzeugt wird und wo die harten Grenzen sind.

Architektur in einem Absatz

zplcloud proxy öffnet eine ausgehende TLS-Verbindung zu api.zplcloud.com (SignalR). Kein eingehender Port, keine NAT-Regel, kein VPN. Öffnest du in der Plattform eine Datenquelle, schickt das Backend dem Agent ein Request-Objekt - Basis-Query, Filter, Sortierung, Offset, Limit. Der Agent baut daraus T-SQL, führt es mit deinem Datenbankbenutzer aus und liefert die Zeilen zurück. Der Connection-String existiert nur im Prozess des Agents und in dessen lokaler Konfiguration.

Schritt 1 - Agent mit einem oder mehreren Servern starten

# Mehrere --sql-Flags sind erlaubt; der NAME ist das, was du später in der Plattform auswählst.
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"

Dasselbe ohne Secrets in der Kommandozeile (die landen sonst in der Shell-History):

# Windows PowerShell - eine Variable je Server, der Name steht in der Mitte
$env:ZPLCLOUD_SQL_PROD_CONNECTION = "Server=127.0.0.1;Database=erp;User Id=zplcloud;Password=…;Encrypt=True;TrustServerCertificate=True"
zplcloud proxy --agent "Lager"

Der Startbanner listet, was gefunden wurde: SQL servers: PROD, WAREHOUSE. Die Authentifizierung gegenüber der Plattform läuft über --api-key <key> oder ZPLCLOUD_API_KEY.

Für den unbeaufsichtigten Betrieb dauerhaft ablegen:

• Windows: setx ZPLCLOUD_SQL_PROD_CONNECTION "…" oder zplcloud proxy --agent "Lager" --service-install --api-key sk_zplcloud_…
• Linux/Raspberry Pi: dasselbe --service-install; es schreibt eine systemd-Unit zplcloud-agent.service mit Restart=always
• Datei statt Env: sqlservers.json neben der Binary oder unter ~/.zplcloud/, Aufbau { "sqlServers": { "PROD": "Server=…" } }
• Docker: ZPLCLOUD_SQL_PROD_CONNECTION in docker-compose.agent.yml

Connection-String-Details, die sonst eine Stunde kosten

• Encrypt=True;TrustServerCertificate=True ist das pragmatische Paar für einen internen Server mit selbstsigniertem Zertifikat. TrustServerCertificate fällt weg, sobald ein echtes Zertifikat da ist.
• Eine benannte Instanz braucht Server=host\\INSTANZ, ein abweichender Port Server=host,1433 - Komma, kein Doppelpunkt.
• Nimm einen eigenen SQL-Login mit SELECT auf genau den Tabellen, die die Labels brauchen. Der Agent führt alles als dieser Benutzer aus - die Datenbank ist die Rechtegrenze, nicht die Plattform.

Schritt 2 - Datenquelle anlegen

Unter Datenquellen erscheint der laufende Agent als Remote SQL Server mit einem Chip je konfiguriertem Namen. Ein Klick auf den Chip füllt das Formular vor.

Test führt SELECT 1 aus und liefert server · datenbank. Felder liest die Spalten-Metadaten über SELECT TOP 1 * mit CommandBehavior.SchemaOnly - das Schema kommt, ohne Daten zu laden. Liefert eine stark verschachtelte Query kein Schema, versucht es der Agent einmal mit SingleRow.

Schritt 3 - was der Agent tatsächlich ausführt

Deine Basis-Query wird als Subquery gekapselt, Filter, Sortierung und Paging hängt der Agent an:

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

Drei Punkte lohnen den zweiten Blick:

1. Werte sind Parameter, nie String-Verkettung. Der Filter-Builder erzeugt @p0, @p1, … und bindet die Werte über SqlCommand.Parameters. Es gibt keine Stelle, an der ein eingegebener Wert zu SQL-Text wird.

2. Paging ist nativ. limit 10 wird zu FETCH NEXT 10 ROWS ONLY; die Arbeit macht SQL Server, über die Leitung gehen zehn Zeilen - nicht eine Million.

3. Die Gesamtzahl ist eine eigene Abfrage. Wenn du den Total willst, läuft SELECT COUNT(*) FROM (<basis>) AS ds mit demselben WHERE und denselben Parametern.

Die harten Grenzen (aus dem Agent-Quellcode)

Brauchst du mehr als 1000 Zeilen in einer Ansicht - Batch-Druck, ein ganzer Katalog - blättert die Plattform mit wachsendem OFFSET durch. Jede Seite ist ein eigener 1000-Zeilen-Request gegen deinen Server, der Speicherbedarf bleibt also konstant, egal wie groß das Gesamtergebnis ist.

15 Sekunden Timeout sind Absicht. Wenn deine Basis-Query nicht in 15 Sekunden antwortet, gehört sie in eine indizierte View oder eine Tabelle mit passendem Index - nicht in eine Label-Datenquelle.

Schritt 4 - im Designer und in Print Views nutzen

• Designer → Tab Testdaten → Datenquelle: Datenquelle wählen, Laden drücken. Die Feld-Bindings rendern mit echten Zeilen statt Platzhaltertext - du siehst die tatsächlichen Feldlängen, bevor irgendetwas beim Drucker landet.
• Print Views → Konfiguration → Datenquelle (Datenhub): Vorschau und Druck der View nutzen die Live-Query. Die Bedienung sieht aktuelle Daten, niemand lädt eine CSV neu hoch.

Fehlerbilder und was sie bedeuten

Tarif

Der Datenhub (SQL-Server- und MongoDB-Datenquellen über den CLI-Agent) gehört zum Pro-Tarif. Details auf der Preisseite.

Weiterlesen

• zplcloud CLI - Kommandos, Service-Installation, USB, Watch-Folder
• Agent als Docker-Container
• Cloud-Integration / Verbindungen