Executar consultas parametrizadas

As consultas parametrizadas permitem-lhe manter placeholders em SQL e fornecer valores em tempo de execução. A extensão PostgreSQL associa esses valores como parâmetros de consulta; não cola valores no texto SQL.

Use esta página quando quiser executar SQL copiado de ferramentas ou código de aplicação que utilizam marcadores de posição como :name, $1, ou ?.

Sintaxes de placeholder suportadas

O editor de consultas deteta estes estilos de marcadores fora de cadeias de caracteres, comentários, conversões de tipo, fatias de array, corpos delimitados por cifrões e operadores JSON do PostgreSQL.

Marcadores de posição nomeados

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

Os marcadores nomeados fazem distinção entre maiúsculas e minúsculas. As ocorrências do mesmo nome partilham a mesma linha da grelha.

Marcadores posicionais do PostgreSQL

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

$N os marcadores de posição são posicionais dentro da afirmação que os contém.

Marcadores de posição posicionais Qmark

select id, email
from users
where active = ?;

? Os marcadores de posição funcionam por ordem da esquerda para a direita. Um ? em qualquer posição de valor funciona como parâmetro, incluindo após operadores de comparação (>=, <=, <>), nos ramos CASE e em LIMIT/OFFSET. Os operadores JSONB ?, ?| e ?& do PostgreSQL e o operador de percurso JSON @? são reconhecidos como operadores, não como parâmetros.

Abra e use o separador Parâmetros

1. Abre ou cria um .sql ficheiro e liga-o a uma base de dados.
2. Execute Query (PostgreSQL), Execute Current Statement (PostgreSQL) ou execute um intervalo SQL selecionado.
3. Se o SQL contiver marcadores de posição, o separador Parâmetros é aberto no painel inferior.
4. Introduza um valor para cada linha, escolha um tipo se necessário e selecione Executar consulta.
5. Após a primeira execução, edite os valores e selecione novamente Executar para repetir a consulta.

O separador mostra uma linha para cada marcador nomeado único e uma linha para cada marcador posicional. Cada linha inclui o nome ou índice do marcador de posição, um campo de valor, uma caixa de seleção NULL, uma lista suspensa de tipo e ações da linha, quando disponíveis.

Scripts com várias instruções

Nota (maio de 2026): versões anteriores deste artigo descreveram incorretamente os índices posicionais como independentes de cada afirmação. O comportamento não mudou; Apenas a documentação é corrigida.

Os parâmetros posicionais ($N, ?) partilham um único array de valores ao longo do script executado. $1 (ou o primeiro ?) em qualquer instrução está sempre associado ao mesmo valor que $1 em qualquer outra instrução. Reutilizar o mesmo índice posicional entre afirmações não lhes dá valores independentes. Se precisares de valores diferentes para o mesmo índice em instruções diferentes, usa parâmetros nomeados (:name) em vez disso.

Se um valor nomeado partilhado não for compatível com uma das instruções que o utiliza, o PostgreSQL devolve o erro e a grelha mantém os seus valores para que possa ajustar e executar novamente.

Valores NULL

Use a caixa de seleção NULL para vincular SQL NULL. Quando assinalado, o campo de valor nessa linha é ignorado.

Se escreveres o texto literal NULL enquanto a caixa de verificação NULL não estiver assinalada, a grelha avisa-te de que o valor é associado como texto NULL, e não como SQL NULL.

Escolher tipos de parâmetros

A lista pendente de tipo assume, por predefinição, auto, o que permite ao PostgreSQL inferir o tipo do parâmetro. Escolha um tipo quando quiser validação do lado do cliente ou ligação mais clara:

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

A validação é flexível. Um aviso não bloqueia a submissão; O PostgreSQL mantém-se como o validador final no momento da execução.

Gerar um plano de consulta com parâmetros

Quando visualiza um plano de consulta para SQL que contém marcadores de lugar, o separador Parâmetros gere o visualizador do plano de consulta em vez de devolver linhas. O botão Executar apresenta o texto Visualize Query Plan e, após a primeira execução, apresenta o texto Visualize again. Introduza valores e selecione o botão para executar EXPLAIN e abra o visualizador do plano de consulta. Este caminho não devolve resultados de consulta.

Usar «Ignorar»

Utilize Ignorar quando a grelha mostrar um token que deve permanecer em SQL, como um operador PostgreSQL válido. Ignorar só é ativado quando o token continua a ser SQL válido sem associação.

Editar SQL e executar novamente

Quando abres o separador Parâmetros , podes editar o SQL e selecionar novamente Executar. A extensão volta a extrair os marcadores de posição e compara o novo SQL templateado com a impressão digital anterior.

Se o conjunto de marcadores mudou, um banner de deriva resume o que mudou, como os marcadores adicionados ou removidos. A extensão propaga os valores quando o marcador de posição continua a corresponder pelo nome ou pelo índice posicional. Se todos os marcadores forem removidos, a grelha fecha e a consulta corre normalmente.

Cancelar e recuperar transações

Enquanto uma execução com parâmetros estiver ativa, o botão de execução passa a ser um controlo de paragem (com a etiqueta Cancelar). Cancelar interrompe o lote em voo, salta os lotes seguintes e mantém o separador Parâmetros aberto com os valores intactos. Uma execução cancelada mostra o estado do lote cancelado em vez de uma falha, por isso as suas linhas não são destacadas como erros.

A extensão não reverte automaticamente transações iniciadas pelo utilizador. Se o cancelamento deixar a ligação num estado de transação abortada, o separador Parâmetros mostra um aviso de recuperação com Executar ROLLBACK. Selecione-o para emitir uma instrução explícita ROLLBACK na mesma conexão e, em seguida, execute o script novamente.

Rever falhas e tentar novamente

Quando uma execução parametrizada falha, o separador Parâmetros mantém os seus valores e mostra o estado falhado com o resumo de erro da base de dados. Selecione Ver Mensagens para abrir os detalhes completos da mensagem.

As execuções canceladas mostram o estado de cancelada separadamente das execuções falhadas, e os lotes posteriores que não foram executados são marcados como ignorados.

Depois de definir um valor ou tipo, selecione novamente Executar. O separador limpa os estados obsoletos de falha, cancelamento e realce da linha para a nova tentativa. Se a ligação ainda estiver numa transação abortada, o aviso de recuperação aparece novamente.

Retenção de valor do histórico de consulta

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

Quando ask está ativa, o prompt mostrado após uma execução bem-sucedida oferece Guardar uma vez (manter apenas esta entrada), Guardar sempre (também mudar a definição para always), Saltar (apenas SQL com template) e Não perguntar novamente (também mudar a definição para never).

Os valores são mantidos apenas na memória e são apagados quando o VS Code recarrega ou quando o espaço de trabalho muda. Os valores dos parâmetros são ocultados na telemetria e nos registos.

Advertência PREPARE

PREPARE ... AS SELECT $1 utiliza a sintaxe posicional do PostgreSQL no servidor. A extensão deteta PREPARE instruções e deixa marcadores de posição dentro do PREPARE corpo para o PostgreSQL em vez de as vincular ao cliente. Outras instruções no mesmo script são analisadas normalmente.

Casos MVP não suportados

O MVP não inclui:

• Histórico persistente de valores suportado por disco.
• Conjuntos de parâmetros nomeados ou guardados entre sessões do editor.
• Reutilização no servidor PREPARE/EXECUTE como execução parametrizada no cliente.
• Associação de tipos compostos, array, bytea, intervalo de valores, intervalo, enum ou outros tipos para além dos tipos de lista suspensa suportados.

Conteúdo relacionado

• Editor de consultas e IntelliSense
• Visualizador de plano de consulta
• Início Rápido: Ligue e consulte o PostgreSQL
• Referência de definições