PostgreSQL comme source de données d'étiquettes : une requête, des milliers d'étiquettes

Les données de base des articles se trouvent dans PostgreSQL, et c'est de là que doivent sortir les étiquettes. La voie habituelle est un export CSV, déjà périmé au moment où il se termine. La meilleure voie : la base de données reste la source, et l'impression d'étiquettes l'interroge directement.

Tout ce qui est décrit ici s'applique aussi à MySQL et MariaDB - seule la chaîne de connexion change.

Deux chemins vers la base de données

Via l'agent, lorsque la base de données se trouve dans ton propre réseau. L'agent zplCloudCli ouvre une connexion sortante vers la plateforme, exécute la requête en local et ne renvoie que les lignes de résultat. La chaîne de connexion reste uniquement sur ta machine. Aucun port entrant n'est nécessaire.

Directement depuis le cloud, lorsque la base de données est de toute façon accessible - une Azure Database for PostgreSQL ou Amazon RDS, par exemple. La plateforme se connecte alors elle-même ; la chaîne de connexion est stockée chiffrée en AES dans la base de données de la plateforme et n'est déchiffrée que pour exécuter la requête.

Chemin agent : enregistrer le serveur

L'agent apprend quelles sont ses bases de données via une option, une variable d'environnement ou un fichier. Les trois sont équivalents.

# comme option de démarrage
zplcloud proxy --agent "Warehouse" \
  --postgres WMS="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=...;SSL Mode=Require"

# ou comme variable d'environnement
export ZPLCLOUD_PG_WMS_CONNECTION="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..."
zplcloud proxy --agent "Warehouse"

# ou comme pgservers.json à côté du binaire ou sous ~/.zplcloud/
# { "postgresServers": { "WMS": "Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..." } }

Le nom derrière l'option (WMS) est celui qui apparaît ensuite dans le sélecteur. Pour MySQL, l'option est --mysql, pour MariaDB --mariadb, avec les variables et fichiers correspondants.

Un conseil tiré de la pratique : crée un utilisateur de base de données dédié avec des droits en lecture seule sur exactement les tables dont les étiquettes ont besoin. L'agent n'exécute jamais que des SELECT, mais un compte qui ne peut rien faire de plus reste la garantie la plus solide.

Créer la source de données

Sous Data hub → Sources de données → Nouveau, choisis le type PostgreSQL (agent) ou PostgreSQL (Cloud), puis l'agent et le serveur. Le champ de requête accepte un seul 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

Champs lit les colonnes sans charger de données - elles sont ensuite disponibles comme liaisons dans le concepteur. Test vérifie la connexion.

Ce qu'une requête peut contenir

Les règles sont volontairement strictes, car une source de données sert à lire et non à écrire :

• Un seul SELECT ou WITH, sans point-virgule, sans commentaires, sans instructions multiples.
• Les valeurs de filtre arrivent toujours dans la base de données sous forme de paramètres, jamais sous forme de texte assemblé. Une injection SQL via la ligne de filtre est donc impossible.
• Le filtre, le tri et LIMIT/OFFSET sont appliqués par la base de données, pas par la plateforme. Tes index font leur travail.
• Au maximum 1000 lignes par récupération, délai d'expiration de 15 secondes.

Ces 1000 lignes ne sont pas un plafond pour l'impression : pour les impressions en masse, la plateforme récupère côté serveur un bloc après l'autre, jusqu'à 50 000 étiquettes d'un coup. Un seul bloc est gardé en mémoire à la fois.

Où les données sont utilisées

Une source de données terminée est disponible partout où des données sont nécessaires :

• Vues d'impression - une URL protégée avec un formulaire dans lequel quelqu'un recherche par EAN et imprime l'étiquette renvoyée.
• Impression par lots - tous les résultats d'une requête d'un coup, envoyés à l'imprimante par blocs.
• Concepteur - comme données de liaison, pour que l'aperçu affiche de vraies valeurs au lieu d'espaces réservés.

Pièges fréquents

• « La requête doit commencer par SELECT. » Un point-virgule final suffit à déclencher ce message. Supprime-le.
• Aucune colonne trouvée. Les colonnes calculées ont besoin d'un nom : SELECT price 1.19 AS gross au lieu de SELECT price 1.19.
• La connexion échoue. Les serveurs PostgreSQL accessibles exigent généralement TLS : SSL Mode=Require a sa place dans la chaîne de connexion.
• Agent hors ligne. L'agent maintient lui-même la connexion. La vue d'ensemble des agents dans le data hub indique lesquels sont présents et quels serveurs ils signalent.