PostgreSQL como fonte de dados de etiquetas: uma consulta, milhares de etiquetas

Os dados mestres dos artigos estão no PostgreSQL, e é de lá que as etiquetas devem sair. O caminho usual é uma exportação CSV que já está desatualizada no momento em que termina. O caminho melhor: o banco de dados continua sendo a fonte, e a impressão de etiquetas o consulta diretamente.

Tudo o que está descrito aqui vale também para MySQL e MariaDB - só a string de conexão é diferente.

Dois caminhos até o banco de dados

Pelo agente, quando o banco de dados está dentro da sua própria rede. O agente zplCloudCli abre uma conexão de saída para a plataforma, executa a consulta localmente e devolve apenas as linhas de resultado. A string de conexão fica somente na sua máquina. Nenhuma porta de entrada é necessária.

Direto da nuvem, quando o banco de dados já é acessível de qualquer forma - um Azure Database for PostgreSQL ou um Amazon RDS, por exemplo. Nesse caso, a plataforma se conecta por conta própria; a string de conexão é armazenada criptografada com AES no banco de dados da plataforma e só é descriptografada para executar a consulta.

Caminho do agente: registre o servidor

O agente fica sabendo dos seus bancos de dados por uma opção, uma variável de ambiente ou um arquivo. As três formas são equivalentes.

# como opção de inicialização
zplcloud proxy --agent "Warehouse" \
  --postgres WMS="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=...;SSL Mode=Require"

# ou como variável de ambiente
export ZPLCLOUD_PG_WMS_CONNECTION="Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..."
zplcloud proxy --agent "Warehouse"

# ou como pgservers.json ao lado do binário ou em ~/.zplcloud/
# { "postgresServers": { "WMS": "Host=pg.internal.lan;Database=wms;Username=zplcloud;Password=..." } }

O nome depois da opção (WMS) é o que aparece mais tarde no seletor. Para MySQL, a opção é --mysql; para MariaDB, --mariadb, com variáveis e arquivos correspondentes.

Uma dica da prática: crie um usuário de banco de dados dedicado, com permissão somente de leitura exatamente nas tabelas de que as etiquetas precisam. O agente só executa SELECT, mas uma conta que não pode fazer mais do que isso é a garantia mais forte.

Criando a fonte de dados

Em Data Hub → Fontes de dados → Nova, escolha o tipo PostgreSQL (agente) ou PostgreSQL (Cloud) e, em seguida, o agente e o servidor. O campo de consulta aceita um único 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

Campos lê as colunas sem carregar nenhum dado - depois disso, elas ficam disponíveis no designer como bindings. Testar verifica a conexão.

O que uma consulta pode conter

As regras são deliberadamente rígidas, porque uma fonte de dados existe para ler, não para escrever:

• Apenas um único SELECT ou WITH, sem ponto e vírgula, sem comentários, sem múltiplas instruções.
• Os valores de filtro chegam ao banco de dados sempre como parâmetros, nunca como texto montado. Por isso, SQL injection pela linha de filtro não é possível.
• Filtro, ordenação e LIMIT/OFFSET são aplicados pelo banco de dados, não pela plataforma. Seus índices fazem o trabalho deles.
• No máximo 1000 linhas por busca, timeout de 15 segundos.

Essas 1000 linhas não são um teto para a impressão: em execuções em lote, a plataforma busca no servidor um bloco após o outro, até 50.000 etiquetas de uma vez. Apenas um bloco fica na memória por vez.

Onde os dados vão parar

Uma fonte de dados pronta fica disponível em todo lugar onde há necessidade de dados:

• Print Views - uma URL protegida com um formulário em que alguém busca por EAN e imprime a etiqueta retornada.
• Impressão em lote - todos os resultados de uma consulta de uma vez, enviados à impressora em blocos.
• Designer - como dados de binding, para que a pré-visualização mostre valores reais em vez de placeholders.

Armadilhas comuns

• "A consulta precisa começar com SELECT." Um ponto e vírgula no final já basta para provocar isso. Remova-o.
• Nenhuma coluna encontrada. Colunas calculadas precisam de um nome: SELECT price 1.19 AS gross em vez de SELECT price 1.19.
• A conexão falha. Servidores PostgreSQL acessíveis diretamente costumam exigir TLS: SSL Mode=Require precisa estar na string de conexão.
• Agente não está online. O próprio agente mantém a conexão. A visão geral de agentes no Data Hub mostra quais estão presentes e quais servidores eles informam.