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

• A extensão PostgreSQL instalada a partir do Visual Studio Marketplace no Visual Studio Code ou do Open VSX Registry no Cursor.
• 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 o 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.

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 exibição ou ajustar o plano à janela.
• Use o painel Opções para alterar a direção do layout e a métrica de cor que realça os 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.

Exibição Icicle

Use a Exibição Icicle quando quiser um resumo visual de largura total que mostre 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.

Quando um plano inclui estatísticas de serialização – de EXPLAIN (ANALYZE, SERIALIZE) no PostgreSQL 17 e posterior - um botão Serialização aparece na barra de ferramentas. Selecione-o para analisar o tempo, o volume de saída, o formato e o uso do buffer envolvidos na serialização da saída da consulta.

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 principais e os detalhes de análise específicos do plano.
• I/O aparece quando o plano inclui dados em buffer. Para planos paralelos, o uso de buffer é dividido em Total do nó (inclui os os trabalhos), Líder e uma linha por processo de trabalho. Se o plano não tiver dados de buffer por trabalho, a guia solicitará que você execute EXPLAIN (ANALYZE, VERBOSE, BUFFERS).
• Trabalhos aparece para os nós paralelos que relatam dados por trabalho. Mostra a Inicialização Real, o Total Real, as Linhas Reais e os Loops Reais de cada trabalho.
• As condições são exibidas quando o nó expõe filtros, condições de junção ou predicados semelhantes.

Use esse painel para comparar o trabalho estimado com o real, inspecionar os 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 de 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 esse nó com o Copilot (ou Analisar esse nó com a IA no Cursor).
3. Examine a nova sessão de chat do modo de Agente para a 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:

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

• Editor de consultas e IntelliSense
• integração com o Copilot
• Modo de agente
• Referência de comandos
• Referência de configurações