PostgreSQL をラベルのデータソースに: クエリ 1 本で数千枚のラベル

商品マスターデータは PostgreSQL にあり、ラベルはそこから作りたい。よくある方法は CSV エクスポートですが、書き出しが終わった時点でもう古くなっています。より良い方法は、データベースを情報源のままにして、ラベル印刷から直接クエリすることです。

ここで説明する内容は、MySQL と MariaDB にもすべて当てはまります。違うのは接続文字列だけです。

データベースに接続する 2 つの方法

エージェント経由: データベースが自社ネットワーク内にある場合です。zplCloudCli エージェントがプラットフォームへ送信方向の接続を張り、ローカルでクエリを実行して、結果の行だけを送り返します。接続文字列はお客様のマシンにしか存在しません。受信ポートは不要です。

クラウドから直接: データベースがもともと外部から到達可能な場合です。たとえば Azure Database for PostgreSQL や Amazon RDS がこれに当たります。この場合はプラットフォーム自身が接続します。接続文字列はプラットフォームのデータベースに AES で暗号化して保存され、クエリを実行するときにだけ復号されます。

エージェント経由: サーバーを登録する

エージェントには、オプション、環境変数、ファイルのいずれかでデータベースを伝えます。3 つとも同等です。

# 起動オプションとして指定
zplcloud proxy --agent "Warehouse" \
  --postgres WMS="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=...;SSL Mode=Require"

# または環境変数として指定
export ZPLCLOUD_PG_WMS_CONNECTION="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..."
zplcloud proxy --agent "Warehouse"

# または pgservers.json としてバイナリの隣か ~/.zplcloud/ に配置
# { "postgresServers": { "WMS": "Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..." } }

オプションの後ろに付けた名前 (WMS) が、後で選択画面に表示されます。MySQL ならオプションは --mysql、MariaDB なら --mariadb で、環境変数とファイルもそれぞれ対応するものを使います。

実務からのヒントを 1 つ。ラベルに必要なテーブルだけに読み取り専用の権限を持つ、専用のデータベースユーザーを作成してください。エージェントが実行するのは SELECT だけですが、それ以上のことができないアカウントのほうが、より確かな保証になります。

データソースを作成する

データハブ → データソース → 新規 で種類 PostgreSQL (エージェント) または PostgreSQL (Cloud) を選び、続いてエージェントとサーバーを選びます。クエリ欄には SELECT を 1 つだけ入力します。

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

項目 は、データを読み込まずに列だけを読み取ります。読み取った列は、その後デザイナーでバインディングとして使えます。テスト は接続を確認します。

クエリに書けること

データソースは読み取りのためのもので、書き込みのためのものではありません。そのためルールは意図的に厳しくしてあります。

• 使えるのは SELECT または WITH 1 つだけです。セミコロン、コメント、複数のステートメントは使えません。
• フィルターの値は常にパラメーターとしてデータベースに渡され、組み立てたテキストとして渡されることはありません。したがって、フィルター行を通じた SQL インジェクションは起こりえません。
• フィルター、並べ替え、LIMIT/OFFSET は、プラットフォームではなくデータベースが適用します。インデックスがきちんと役目を果たします。
• 1 回の取得は最大 1000 行、タイムアウトは 15 秒です。

この 1000 行は印刷の上限ではありません。一括印刷では、プラットフォームがサーバー側でチャンクを 1 つずつ順に取得し、一度に最大 50,000 枚のラベルを印刷できます。メモリに保持されるのは、常に 1 チャンク分だけです。

データの行き先

完成したデータソースは、データが必要なあらゆる場所で使えます。

• プリントビュー - フォーム付きの保護された URL です。担当者が EAN で検索し、見つかったラベルを印刷します。
• バッチ印刷 - クエリのヒットをすべてまとめて、チャンクごとにプリンターへ送ります。
• デザイナー - バインディング用のデータとして使い、プレビューにプレースホルダーではなく実際の値を表示します。

よくある落とし穴

• 「The query must start with SELECT.」 末尾にセミコロンが 1 つあるだけで、このエラーになります。削除してください。
• 列が見つからない。 計算列には名前が必要です。SELECT price 1.19 ではなく SELECT price 1.19 AS gross と書きます。
• 接続に失敗する。 外部から到達可能な PostgreSQL サーバーは、たいてい TLS を必須にしています。接続文字列に SSL Mode=Require を入れてください。
• エージェントがオンラインにならない。 接続を維持するのはエージェント自身です。データハブのエージェント一覧で、どのエージェントが接続しているか、それぞれがどのサーバーを報告しているかを確認できます。