SQL Server como fonte de dados: o ciclo de exportação, eliminado

O ciclo de exportação, e por que ele quebra

Os dados das etiquetas vivem em um ERP, um WMS ou um banco Azure SQL. O fluxo usual é exportar para CSV, corrigir os nomes das colunas, carregar, imprimir - e repetir amanhã, porque o CSV já está obsoleto.

O data hub zplCloud elimina a exportação. Um agente CLI dentro da sua rede detém a string de conexão SQL Server, a plataforma envia a ele uma descrição de consulta, e apenas as linhas de resultado voltam. O banco nunca é exposto à internet e as credenciais nunca são armazenadas no cloud.

Este post é a mecânica exata: o que roda onde, qual SQL é gerado e quais são os limites rígidos.

Arquitetura em um parágrafo

zplcloud proxy abre uma conexão TLS de saída para api.zplcloud.com (SignalR). Sem porta de entrada, sem regra NAT, sem VPN. Quando você abre uma fonte de dados na plataforma, o backend envia ao agente um objeto de solicitação - consulta base, filtro, ordenação, offset, limite - e o agente o transforma em T-SQL, executa contra seu SQL Server com seu usuário de banco, e retorna as linhas. A string de conexão existe apenas na memória do processo do agente e na sua configuração local.

Passo 1 - inicie o agente com um ou mais servidores

# Vários flags --sql são permitidos; o NOME é o que você escolhe na plataforma.
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 sem colocar segredos na linha de comando (eles cairiam no histórico do shell):

# Windows PowerShell - uma variável por servidor, nome no meio
$env:ZPLCLOUD_SQL_PROD_CONNECTION = "Server=127.0.0.1;Database=erp;User Id=zplcloud;Password=…;Encrypt=True;TrustServerCertificate=True"
zplcloud proxy --agent "Lager"

O banner de inicialização lista o que encontrou: SQL servers: PROD, WAREHOUSE. A autenticação na plataforma usa --api-key <key> ou ZPLCLOUD_API_KEY.

Persista para operação não assistida:

• Windows: setx ZPLCLOUD_SQL_PROD_CONNECTION "…", ou zplcloud proxy --agent "Lager" --service-install --api-key sk_zplcloud_…
• Linux/Raspberry Pi: mesmo flag --service-install; ele escreve uma unidade systemd zplcloud-agent.service com Restart=always
• Arquivo em vez de env: sqlservers.json ao lado do binário ou em ~/.zplcloud/, formato { "sqlServers": { "PROD": "Server=…" } }
• Docker: ZPLCLOUD_SQL_PROD_CONNECTION no docker-compose.agent.yml

Notas sobre strings de conexão que custam uma hora às pessoas

• Encrypt=True;TrustServerCertificate=True é o par pragmático para um servidor interno com certificado autoassinado. Remova TrustServerCertificate quando tiver um certificado real.
• Uma instância nomeada precisa de Server=host\INSTANCE; uma porta não padrão é Server=host,1433 - vírgula, não dois pontos.
• Use um login SQL dedicado com SELECT exatamente nas tabelas de que as etiquetas precisam. O agente executa tudo como esse usuário, então o banco é o limite de permissões - não a plataforma.

Passo 2 - crie a fonte de dados

Em Fontes de dados, o agente em execução aparece sob Remote SQL Server com um chip por nome configurado. Clicar em um chip pré-preenche o formulário.

Testar executa SELECT 1 e retorna servidor · banco de dados. Campos lê os metadados das colunas via SELECT TOP 1 * com CommandBehavior.SchemaOnly - ele busca o esquema sem puxar dados. Se uma consulta muito aninhada não retornar esquema, o agente tenta novamente uma vez com SingleRow.

Passo 3 - o que o agente realmente executa

Sua consulta base é envolvida como subconsulta. Filtro, ordenação e paginação são adicionados pelo 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

Três coisas merecem ser lidas duas vezes:

1. Valores são parâmetros, nunca concatenação de strings. O construtor de filtros emite @p0, @p1, … e vincula os valores via SqlCommand.Parameters. Não há nenhum lugar onde um valor digitado pelo usuário se torna texto SQL.

2. A paginação é nativa. limit 10 vira FETCH NEXT 10 ROWS ONLY; o SQL Server faz o trabalho e retorna dez linhas pelo fio, não um milhão.

3. A contagem de linhas é uma consulta separada. Quando você pede o total, o agente executa SELECT COUNT(*) FROM (<base>) AS ds com o mesmo WHERE e os mesmos parâmetros.

Os limites rígidos (do código-fonte do agente)

Se você precisar de mais de 1000 linhas em uma visão - impressão em lote, um catálogo completo - a plataforma pagina pelo conjunto de resultados com OFFSET crescente. Cada página é sua própria solicitação de 1000 linhas contra seu servidor, então a memória permanece plana independentemente do total.

Um timeout de 15 segundos é deliberado. Se sua consulta base não consegue responder em 15 segundos, ela pertence a uma view indexada ou a uma tabela com o índice certo, não a uma fonte de dados de etiquetas.

Passo 4 - use no designer e nas Print Views

• Designer → aba Dados Teste → Fonte de dados: escolha a fonte de dados e pressione Carregar. Os bindings de campos são renderizados com linhas reais em vez de texto de espaço reservado, então você vê os comprimentos reais dos campos antes que qualquer coisa chegue a uma impressora.
• Print Views → configuração → Fonte de dados (data hub): a visualização da visão e sua impressão usam a consulta ao vivo. O operador vê dados atuais; ninguém recarrega um CSV.

Modos de falha e o que significam

Plano

O data hub (fontes de dados SQL Server e MongoDB através do agente CLI) faz parte do plano Pro. Detalhes na página de preços.

Relacionados

• CLI zplCloud - comandos, instalação de serviço, USB, watch folders
• Agente como contêiner Docker
• Cloud Integration / Connections