Banco de dados (SQL)

O componente Consulta de Banco roda uma consulta SQL em um banco de dados e mostra o resultado como uma tabela na página.

Somente PostgreSQL (por enquanto)

Hoje o único banco suportado é o PostgreSQL. Suporte a outros bancos está planejado.

Passo a passo

Com o componente Consulta de Banco selecionado, na aba Config:

1. Credencial — escolha uma credencial existente em Selecione credencial... ou clique em Nova credencial. O formulário pede: Nome, Host, Porta (5432 é o padrão do PostgreSQL), Banco de Dados, Usuário e Senha.
2. Consulta SQL — escreva o seu SELECT.
3. Salvar — guarda a credencial + a consulta juntas (a "integração").
4. Executar consulta — testa a consulta (roda a versão salva — veja abaixo).

Credenciais são pessoais

Cada credencial pertence a um usuário

As credenciais são por usuário — uma proteção para que ninguém acesse um banco com as credenciais de outra pessoa.

Na prática, isto tem uma consequência importante: se outro administrador editar um workflow que usa uma consulta de banco e salvar sem selecionar a própria credencial, a credencial anterior é apagada — e a consulta para de funcionar até que uma nova seja escolhida. Ao editar a consulta de banco de outra pessoa, sempre selecione (ou crie) a sua própria credencial antes de salvar.

Salve antes de testar

Não dá para testar sem salvar

O botão Executar consulta roda a versão salva da consulta — a mesma que o workflow publicado vai usar. Se nada foi salvo, nada roda.

Então, antes de testar (ou publicar), confirme que a credencial está selecionada e que a consulta está escrita, e clique em Salvar. Só depois use Executar consulta.

Sempre teste com "Executar consulta"

Rodar a consulta pelo Executar consulta é a melhor forma de pegar erros cedo: usuário/senha errados, tabela que não existe e outros problemas comuns de banco aparecem aqui — antes de o usuário final topar com eles.

Usando valores dos campos na consulta

Dentro do SQL você usa as mesmas expressões {{ }} do resto do editor — com $form, $args, $user, operadores e funções (veja Expressões e variáveis):

SELECT * FROM pedidos WHERE cliente_id = {{ $form.Cliente_ID }}

SELECT * FROM pessoas
WHERE nome ILIKE {{ CONCAT('%', $form.Busca, '%') }}

Dica: digite {{ (ou $) na caixa de SQL para abrir a lista de campos e variáveis disponíveis.

Sem aspas, sem medo de SQL injection

Não coloque aspas em volta da expressão — nem para texto. Cada {{ ... }} vira um parâmetro enviado separadamente ao banco (nunca texto colado dentro do SQL), então = {{ $form.Nome }} já é o formato certo e seguro.

O formato antigo $Campo continua funcionando

Consultas antigas com $Cliente_ID (um único $, sem chaves) continuam valendo — não precisa migrar nada. Para consultas novas, prefira {{ $form.Cliente_ID }}.

Lembre da regra do "carrega uma vez"

A consulta roda uma única vez, quando a página abre. Por isso, um campo que está na mesma página ainda estará vazio nesse momento — e a consulta não recebe o valor. Para alimentar a consulta, use um $args (parâmetro da URL) ou um valor vindo de uma página anterior. Detalhes em Expressões e variáveis.

Exibindo e usando os resultados

Os resultados aparecem como uma tabela. Nas propriedades você ajusta:

• Espaço entre linhas / colunas (px) — o espaçamento visual da tabela.
• Selecionável — deixa o usuário clicar para selecionar linhas; você define o número máximo de seleções.
• Editável — deixa o usuário editar as células direto na tabela.

O que o usuário seleciona (ou edita) vira o "valor" do componente, que outros campos podem reaproveitar por expressão — por exemplo, pegar uma coluna da linha selecionada:

{{ $form.Consulta_de_Banco.nome }}

Tabela somente leitura vira valor automaticamente

Se a tabela não é Selecionável nem Editável, o resultado inteiro da consulta vira o valor do componente automaticamente — sem o usuário clicar em nada. Isso permite usar uma consulta como fonte de dados invisível: buscar um ID, carregar um cadastro ou validar algo, e usar o resultado em expressões, automações e no envio do formulário.

Como o valor fica gravado:

Resultado da consulta	Valor do componente
1 linha, 1 coluna	o próprio valor (ex.: 42)
Várias linhas, 1 coluna	lista JSON (ex.: ["a","b","c"])
Várias colunas	lista JSON de objetos (ex.: [{"id":1,"nome":"Ana"}, ...])

E como ler esse valor em expressões:

• {{ $form.Consulta.nome }} → a coluna nome da primeira linha;
• {{ $form.Consulta }} → o resultado completo, como texto JSON;
• no envio do formulário, o valor completo vai junto — automações e integrações recebem todas as linhas.

Consulta escondida ("lookup")

Combine com o olhinho do painel de camadas para ocultar o componente: a consulta roda do mesmo jeito, ninguém vê a tabela, e o valor fica disponível para o resto da página — por exemplo, buscar o ID do cliente a partir de um $args da URL e usá-lo em uma automação.

Editar não altera o banco

Marcar a tabela como Editável só muda o valor do componente na página — as edições não são gravadas no banco de dados. Para persistir qualquer mudança, você precisa enviar os dados de volta explicitamente (por exemplo, uma ação de Requisição HTTP).

Veja Expressões e variáveis para os detalhes de como referenciar colunas.

Segurança: pense antes de publicar

Assuma que tudo que a consulta PODE retornar é público

Como as consultas funcionam por baixo dos panos:

• O texto do SQL fica no servidor e só aceita SELECT — quem abre o link não consegue alterar a consulta nem escrever no banco.
• Mas os valores dos parâmetros ({{ }} e $Campo) vêm do navegador de quem usa o link. Qualquer pessoa com o link público pode executar a consulta com outros valores — por exemplo, testar vários IDs em WHERE id = {{ $form.ID }}.
• Por isso, não use $user dentro do SQL como controle de acesso (esse valor também vem do navegador) e não publique em link público uma consulta que alcance dados sensíveis.

Regra prática: avalie a consulta pelo conjunto de tudo que ela consegue retornar com qualquer parâmetro, não só pelo que aparece na tela.