Visualizador de plano de consulta

Use o visualizador de plano de consulta na extensão PostgreSQL para inspecionar a saída do PostgreSQL EXPLAIN sem sair do editor. Você pode gerar um plano no editor de consultas ou no painel de Resultados de Consulta do PostgreSQL, ou abrir, no editor, uma saída de plano existente em JSON ou TEXT. O visualizador é executado da mesma maneira em Visual Studio Code e Cursor.

Pré-requisitos

  • Extensão do PostgreSQL instalada.
  • Uma conexão ativa com um servidor PostgreSQL, se você quiser gerar um plano em tempo real no editor de consultas ou no painel Resultados da Consulta do PostgreSQL.
  • Assistente de IA opcional se você quiser uma análise assistida por IA: instale GitHub Copilot no Visual Studio Code ou use a IA interna no Cursor.
  • A saída opcional EXPLAIN já será aberta no editor se você quiser importar um plano salvo sem se conectar a um banco de dados.

Escolher como abrir um plano

Use o ponto de entrada que corresponde ao fluxo de trabalho:

  • Editor de consultas: Selecione Visualizar Plano de Consulta (PostgreSQL) na barra de ferramentas do editor. Se você não selecionar texto primeiro, a extensão usará o conteúdo atual do editor.
  • Painel Resultados da Consulta PostgreSQL: execute uma consulta e selecione Visualizar Plano de Consulta na barra de ferramentas do painel Resultados da Consulta PostgreSQL para inspecionar a consulta que produziu esse conjunto de resultados.
  • Plano importado: abra qualquer aba do editor que contenha a saída de plano do PostgreSQL e execute PGSQL: Visualizar plano de consulta no Editor a partir da Paleta de Comandos.

Gerar um plano a partir de uma consulta em tempo real

  1. Abra o arquivo SQL que você deseja inspecionar no editor de consultas.
  2. Conecte-se ao banco de dados de destino.
  3. Selecione a instrução que deseja analisar. Se você deixar a seleção vazia, a extensão usará o conteúdo atual do editor.
  4. Selecione Visualizar Plano de Consulta (PostgreSQL) na barra de ferramentas do editor. Você também pode executar a consulta primeiro e, em seguida, selecionar Visualizar Plano de Consulta no painel Resultados da Consulta PostgreSQL .
  5. Em Configurar Plano de Consulta, escolha o formato e as opções desejadas e pressione Enter.
  6. Examine o plano no visualizador.

Configurar opções de plano de consulta

O seletor Configurar Plano de Consulta permite que você escolha o formato de saída e as EXPLAIN opções a serem executadas.

Opção O que muda
JSON Retorna a saída estruturada do plano que funciona melhor em todas as visualizações.
TEXTO Retorna a saída em texto simples EXPLAIN do PostgreSQL e preserva essa fonte na Exibição de origem.
ANALISAR Executa a consulta e inclui estatísticas reais de tempo de execução.
BUFFERS Adiciona estatísticas de uso do buffer. Ao selecioná-lo, ANALYZE é ativado automaticamente.
TEMPO Adiciona dados de tempo reais. Selecioná-lo habilita automaticamente o ANALYZE.
WAL Adiciona estatísticas de uso do WAL. Ao selecioná-lo, ANALYZE é habilitado automaticamente.
VERBOSE Adiciona detalhes adicionais da saída, como informações sobre esquema e colunas.
CUSTOS Inclui valores de custo total e inicialização estimados.
CONFIGURAÇÕES Inclui configurações de planejador que diferem dos padrões.

Caution

EXPLAIN ANALYZE executa a consulta. Se a instrução modificar dados, comoINSERT, , UPDATEDELETEou TRUNCATE, a extensão mostrará um prompt de confirmação antes de continuar.

Abrir um plano salvo no editor

  1. Abra uma guia do editor que contém a saída do PostgreSQL EXPLAIN em formato JSON ou TEXT.
  2. Abra a paleta de comandos (Ctrl+Shift+P).
  3. Execute PGSQL: visualizar o plano de consulta do Editor.
  4. Examine o plano importado no visualizador.

Esse fluxo de trabalho não requer uma conexão de banco de dados ativa. O comando lê o conteúdo atual do editor, para que você possa usá-lo com a saída do plano copiada, com arquivos .json ou .txt salvos, ou com texto do plano colado em um editor temporário.

Alternar entre exibições

Use o seletor de exibição na barra de ferramentas para alternar entre a Visualização em árvore, a Visualização em icicle, a Visualização em tabela e a Visualização do código-fonte.

Modo de Exibição de Árvore

O Modo de Exibição de Árvore é aberto por padrão. Use isso quando quiser um diagrama nó a nó do plano de execução.

  • Use os controles de zoom para ampliar, reduzir, redefinir a visualização ou ajustar a planta à janela.
  • Use o painel de opções para alterar a direção do layout e a métrica de cor que realça nós caros ou incomuns.
  • Selecione um nó para abrir o painel de detalhes.
  • Clique com o botão direito do mouse em um nó para ir para outra visualização ou analisar esse nó com o assistente de IA.

Modo de Exibição de Tabela

Use o Modo de Exibição de Tabela quando quiser classificar, pesquisar e comparar muitos nós ao mesmo tempo.

  • O plano é convertido em uma tabela ordenável, em vez de uma árvore expansível.
  • A caixa de pesquisa é exibida apenas no Modo de Exibição de Tabela.
  • A pesquisa encontra correspondências no tipo de nó, nome da relação, nome do índice, alias, texto do filtro e nome do subplano.
  • Use o seletor predefinido para se concentrar em Desempenho, Estimativas, Eficiência ou E/S ou personalizar as colunas de métrica visíveis.

Visualização Icicle

Use a Exibição em Icicle quando quiser uma visão geral visual em largura total que mostra onde o custo, o tempo ou o uso de buffer estão concentrados.

  • O modo de exibição Icicle é um modo de exibição separado, não um painel dentro do Modo de Exibição de Árvore.
  • Use o painel de opções para alternar entre predefinições, alterar a métrica de largura, alterar a métrica de cor e alternar entre o escopo próprio e o total, onde houver suporte.
  • Passe o mouse sobre um bloco para inspecionar suas métricas ou clique com o botão direito do mouse em um bloco para abrir detalhes ou ir para outro modo de exibição.

Visualização da origem

Use a Visualização da origem quando quiser a saída original do plano.

  • Selecione Opções para alternar entre o modo Árvore e Texto .
  • O painel mostra se a origem importada ou gerada é JSON ou TEXT.
  • Expandir tudo e Recolher tudo aparecem na barra de ferramentas somente enquanto a Exibição de código-fonte estiver ativa.
  • No modo Texto , o plano é aberto em um editor somente leitura. No modo Árvore , você pode inspecionar a estrutura analisada como uma árvore recolhível.

Selecione Copiar Plano a qualquer momento para copiar a origem do plano atual para a área de transferência. Os planos JSON são copiados em formato formatado e os planos TEXT são copiados como sua origem original.

Inspecionar nós de plano

Selecione um nó na Visualização em árvore, na Visualização em tabela ou na Visualização Icicle para abrir o painel de detalhes.

  • Geral mostra o tipo de nó, as métricas de chave e os detalhes de análise específicos do plano.
  • I/O aparece quando o plano inclui dados em buffer.
  • As condições são exibidas quando o nó expõe filtros, condições de junção ou predicados semelhantes.

Use este painel para comparar o trabalho estimado com o real, inspecionar nós com uso intenso de buffer e confirmar quais predicados estão determinando o plano de execução.

Analisar planos com o assistente de IA

Use o assistente de IA quando quiser que a extensão abra um chat de análise com o plano atual como contexto.

Analisar o plano completo

  1. Abra o plano no visualizador.
  2. Selecione Analisar com Copilot (ou Analisar com IA no Cursor).
  3. Escolha se deseja incluir o texto da consulta SQL com a análise.
  4. Examine a nova sessão de chat que é aberta no modo Agente.

Se o plano veio do PGSQL: Visualizar o Plano de Consulta do Editor e ainda não houver nenhum texto SQL útil, a extensão poderá solicitar que você insira a consulta primeiro para que a IA tenha um contexto melhor.

Analisar um nó

  1. Clique com o botão direito do mouse no nó que você deseja inspecionar.
  2. Selecione Analisar este nó com Copilot (ou Analisar este nó com IA no Cursor).
  3. Examine a nova sessão de chat do modo Agente para análise específica do nó.

Controlar se o texto SQL está incluído

A pgsql.copilot.autoAttachQuery configuração controla como a extensão lida com o texto SQL quando inicia a análise de IA:

  • Pergunte se deseja incluir o SQL todas as vezes
  • Sempre inclua SQL sem solicitar
  • Nunca inclua SQL

Quando você opta por incluir ou excluir o SQL do prompt, a extensão também pode se oferecer para lembrar dessa opção para sessões futuras.

Usar a ferramenta de plano de consulta no modo agent

O visualizador armazena em cache o plano atual e o expõe ao assistente de IA por meio da pgsql_query_plan ferramenta ou o equivalente do MCP em hosts com suporte. Essa ferramenta dá suporte a essas ações:

Ação Use-o para
get_summary Obtenha um resumo de todo o plano antes de detalhar.
get_node Inspecione um nó por ID.
get_subtree Inspecione um nó junto com seus descendentes.
list_nodes Localize nós por tipo ou custo mínimo.

Se você quiser que a IA comece a partir da consulta ativa em vez do visualizador, use Analisar o Desempenho da Consulta do submenu AI Query Actions do editor. Use o visualizador quando quiser inspecionar o plano primeiro e, em seguida, entregar esse plano exato à IA.

Dicas para análise de desempenho

  • Use ANALYZE quando for seguro executar a instrução. As estimativas, por si só, podem ocultar premissas incorretas sobre a contagem de linhas.
  • Compare as contagens de linhas estimadas e reais para detectar estatísticas obsoletas ou filtrar problemas de seletividade.
  • Alterne para o Modo de Exibição de Tabela quando o plano for grande e você precisar de pesquisas ou comparações de métrica lado a lado.
  • Alterne para a Visualização do código-fonte quando precisar do plano em formato bruto para um problema, uma revisão de código ou uma discussão com colegas.

Conteúdo relacionado

  • Last updated on