Executar consultas parametrizadas

Consultas parametrizadas permitem manter placeholders no SQL e informar valores em tempo de execução. A extensão PostgreSQL associa esses valores como parâmetros de consulta; ele não cola valores no texto SQL.

Use esta página quando quiser executar o SQL copiado de ferramentas ou código de aplicativo que usam espaços reservados como :name, $1ou ?.

Sintaxes de marcador compatíveis

O editor de consultas detecta esses estilos de espaço reservado fora de sequências de caracteres, comentários, conversões, fatias de matriz, blocos delimitados por cifrões e operadores JSON do PostgreSQL.

Espaços reservados nomeados

select id, email
from users
where id = :user_id;

Os espaços reservados nomeados diferenciam maiúsculas de minúsculas. Ocorrências repetidas do mesmo nome compartilham uma linha da grade.

Marcadores posicionais do PostgreSQL

select id, email
from users
where id = $1;

Os espaços reservados $N são posicionais dentro da instrução que os contém.

Espaços reservados posicionais do Qmark

select id, email
from users
where active = ?;

Os espaços reservados ? funcionam na ordem da esquerda para a direita. Um ? em qualquer posição de valor funciona como parâmetro, inclusive após operadores de comparação (>=, <=, <>), em ramificações CASE e em LIMIT/OFFSET. Os operadores JSONB do PostgreSQL ?, ?| e ?& e o operador de caminho JSON @? são reconhecidos como operadores, não parâmetros.

Importante

Use um estilo de espaço reservado por instrução. Uma instrução que mistura :name com $N ou mistura $N com ? é rejeitada antes da execução.

Abrir e usar a guia Parâmetros

  1. Abra ou crie um .sql arquivo e conecte-o a um banco de dados.
  2. Execute Execute Query (PostgreSQL),Execute Current Statement (PostgreSQL) ou execute um intervalo de SQL selecionado.
  3. Se o SQL contiver espaços reservados, a guia Parâmetros será aberta no painel inferior.
  4. Insira um valor para cada linha, escolha um tipo, se necessário, e selecione Executar consulta.
  5. Após a primeira execução, edite valores e selecione Executar novamente para repetir a consulta.

A aba mostra uma linha para cada marcador nomeado único e uma linha para cada marcador posicional. Cada linha inclui o nome ou índice do espaço reservado, uma entrada de valor, uma caixa de seleção NULL, uma lista suspensa de tipos e ações da linha, quando disponíveis.

Scripts com várias instruções

Observação (maio de 2026): as versões anteriores deste artigo descreviam incorretamente os índices posicionais como independentes por cada instrução. O comportamento não foi alterado; apenas a documentação está corrigida.

Parâmetros posicionais ($N, ?) compartilham uma matriz de valor único no script executado. $1 (ou o primeiro ?) em qualquer instrução sempre se associa ao mesmo valor que $1 em qualquer outra instrução. Reutilizar o mesmo índice posicional em diferentes instruções não faz com que elas tenham valores independentes. Se você precisar de valores diferentes para o mesmo índice em instruções diferentes, use parâmetros nomeados (:name) em vez disso.

Se um valor nomeado compartilhado não for compatível com uma das instruções que o usa, o PostgreSQL retornará o erro e a grade manterá seus valores para que você possa ajustar e executar novamente.

Valores NULL

Use a caixa de seleção NULL para associar o SQL NULL. Quando verificado, o campo de valor é ignorado para essa linha.

Se você digitar o texto literal NULL enquanto a caixa de seleção NULL estiver desativada, a grade alertará que o valor é vinculado como texto NULL, e não como SQL NULL.

Escolher tipos de parâmetro

A lista suspensa de tipos usa como padrão auto, o que permite ao PostgreSQL inferir o tipo de parâmetro. Escolha um tipo quando quiser validação do lado do cliente ou associação mais clara:

  • text
  • integer
  • bigint
  • numeric
  • boolean
  • date
  • timestamp
  • timestamptz
  • uuid
  • json
  • jsonb

A validação é flexível. Um aviso não bloqueia o envio; PostgreSQL continua sendo o validador final no momento da execução.

Gerar um plano de consulta com parâmetros

Quando você visualiza um plano de consulta para SQL que contém espaços reservados, a guia Parâmetros conduz o visualizador do plano de consulta em vez de retornar linhas. O botão Executar mostra Visualizar plano de consulta e, após a primeira execução, mostra Visualizar novamente. Insira valores e selecione o botão para executar EXPLAIN e abrir o visualizador do plano de consulta. Esse caminho não retorna os resultados da consulta.

Usar Ignorar

Use Ignorar quando a grade exibir um token que deva permanecer no SQL, como um operador válido do PostgreSQL. Ignore fica habilitado somente quando o token permanece como SQL válido sem vinculação.

Editar SQL e executar novamente

Ao abrir a guia Parâmetros , você pode editar o SQL e selecionar Executar novamente. A extensão extrai novamente os espaços reservados e compara o novo SQL modelo com a impressão digital anterior.

Se o conjunto de marcadores tiver sido alterado, uma faixa de descompasso resumirá o que foi alterado, como espaços reservados adicionados ou removidos. A extensão mescla os valores adiante quando o espaço reservado ainda for correspondente por nome ou por índice posicional. Se todos os marcadores forem removidos, a grade se fecha e a consulta é executada normalmente.

Cancelar e recuperar transações

Enquanto uma execução com parâmetros está ativa, o botão Executar muda para um controle de interrupção (rotulado Cancelar). Cancelar interrompe o lote em execução, pula os lotes seguintes e deixa a guia Parâmetros aberta com os valores preservados. Uma execução cancelada mostra o status do lote cancelado em vez de uma falha, portanto, suas linhas não são realçadas como erros.

A extensão não reverte automaticamente transações iniciadas pelo usuário. Se o cancelamento deixar a conexão em um estado de transação anulada, a guia Parâmetros mostrará um aviso de recuperação com Execute ROLLBACK. Selecione-o para emitir um explícito ROLLBACK na mesma conexão e, em seguida, execute o script novamente.

Examinar falhas e tentar novamente

Quando uma execução parametrizada falha, a guia Parâmetros mantém seus valores e mostra o status com falha com o resumo do erro do banco de dados. Selecione Ver Mensagens para abrir os detalhes completos da mensagem.

As execuções canceladas mostram o status de cancelado separadamente das execuções com falha, e os lotes posteriores que não foram executados são marcados como ignorados.

Depois de corrigir um valor ou tipo, selecione Executar novamente. A guia limpa os estados obsoletos de falha, cancelamento e destaque de linha para a nova tentativa. Se a conexão ainda estiver em uma transação anulada, o aviso de recuperação será exibido novamente.

Retenção de valor do Histórico de Consultas

A configuração pgsql.queryPlaceholders.historyValueRetention controla se os valores de parâmetro são mantidos no histórico de consultas na memória da sessão atual:

Valor Behavior
ask Pergunte após cada execução parametrizada bem-sucedida.
always Mantenha os valores das entradas do histórico da sessão sem pedir confirmação.
never Mantenha somente SQL com modelo.

Quando ask estiver ativo, o prompt mostrado após uma execução bem-sucedida oferece Salvar uma vez (manter essa entrada somente), Sempre salvar (também alternar a configuração para always), Ignorar (somente SQL modelo) e Não perguntar novamente (também alternar a configuração para never).

Os valores são mantidos somente na memória e são limpos quando o VS Code é recarregado ou o workspace é alterado. Os valores dos parâmetros são ocultados na telemetria e nos logs.

Ressalva PREPARE

PREPARE ... AS SELECT $1 usa a sintaxe posicional do lado do servidor do PostgreSQL. A extensão detecta as instruções PREPARE e deixa os espaços reservados no corpo de PREPARE para o PostgreSQL, em vez de vinculá-los no cliente. Outras instruções no mesmo script são analisadas normalmente.

Casos de MVP não suportados

O MVP não inclui:

  • Histórico persistente de valores armazenado em disco.
  • Conjuntos de parâmetros nomeados ou salvos entre sessões do editor.
  • Reutilização no servidor PREPARE/EXECUTE como execução parametrizada no cliente.
  • Composite, array, bytea, range, interval, enum ou outra associação de tipo além dos tipos compatíveis de lista suspensa.

Conteúdo relacionado

  • Last updated on