Visualiseur du plan de requête

Utilisez le visualiseur de plan de requête dans l’extension PostgreSQL pour inspecter la sortie PostgreSQL EXPLAIN sans quitter votre éditeur. Vous pouvez générer un plan à partir de l’éditeur de requête ou du panneau Résultats des requêtes PostgreSQL, ou ouvrir une sortie de plan JSON ou TEXT existante à partir de l’éditeur. Le visualiseur s’exécute de la même façon dans Visual Studio Code et cursor.

Prerequisites

  • Extension PostgreSQL installée.
  • Connexion active à un serveur PostgreSQL si vous souhaitez générer un plan en direct à partir de l’éditeur de requête ou du panneau Résultats des requêtes PostgreSQL.
  • Assistant IA facultatif si vous souhaitez une analyse assistée par l’IA : installez GitHub Copilot dans Visual Studio Code, ou utilisez l’IA intégrée dans Cursor.
  • Sortie facultative EXPLAIN déjà ouverte dans l’éditeur si vous souhaitez importer un plan enregistré sans vous connecter à une base de données.

Choisir comment ouvrir un plan

Utilisez le point d’entrée qui correspond à votre flux de travail :

  • Éditeur de requête : sélectionnez Visualiser le plan de requête (PostgreSQL) dans la barre d’outils de l’éditeur. Si vous ne sélectionnez pas le texte en premier, l’extension utilise le contenu de l’éditeur actuel.
  • Panneau Résultats des requêtes PostgreSQL : Exécutez une requête, puis sélectionnez Visualiser le plan de requête dans la barre d’outils du volet Résultats des requêtes PostgreSQL pour inspecter la requête qui a produit ce jeu de résultats.
  • Plan importé : ouvrez n’importe quel onglet d’éditeur qui contient la sortie du plan PostgreSQL, puis exécutez PGSQL : Visualiser le plan de requête à partir de l’éditeur à partir de la palette de commandes.

Générer un plan à partir d’une requête dynamique

  1. Ouvrez le fichier SQL que vous souhaitez inspecter dans l’éditeur de requête.
  2. Connectez-vous à la base de données cible.
  3. Sélectionnez l’énoncé que vous souhaitez analyser. Si vous laissez la sélection vide, l’extension utilise le contenu de l’éditeur actuel.
  4. Sélectionnez Visualiser le plan de requête (PostgreSQL) dans la barre d’outils de l’éditeur. Vous pouvez également exécuter la requête en premier, puis sélectionner Visualiser le plan de requête dans le panneau Résultats des requêtes PostgreSQL .
  5. Dans Configurer le plan de requête, choisissez le format et les options souhaitées, puis appuyez sur Entrée.
  6. Passez en revue le plan dans le visualiseur.

Configurer les options du plan de requête

Le sélecteur Configurer le plan de requête vous permet de choisir le format de sortie et les EXPLAIN options à exécuter.

Option Ce qu’il change
JSON Renvoie un résultat de plan structuré qui fonctionne au mieux dans les différentes vues visuelles.
TEXT Retourne la sortie en texte brut de PostgreSQL EXPLAIN et préserve cette source dans la vue Source.
ANALYSER Exécute la requête et inclut des statistiques d’exécution réelles.
TAMPONS Ajoute des statistiques d’utilisation des mémoires tampons. La sélection de celle-ci active automatiquement ANALYZE.
TIMING Ajoute des données temporelles réelles. La sélection de celle-ci active automatiquement ANALYZE.
WAL Ajoute des statistiques d’utilisation de WAL. La sélection de celle-ci active automatiquement ANALYZE.
VERBOSE Ajoute des détails de sortie supplémentaires, tels que les informations de schéma et de colonne.
COÛTS Inclut les valeurs estimées de démarrage et de coût total.
PARAMÈTRES Inclut les paramètres du planificateur qui diffèrent des valeurs par défaut.

Avertissement

EXPLAIN ANALYZE exécute la requête. Si l’instruction modifie les données, telles que INSERT, , UPDATEDELETEou , l’extension TRUNCATEaffiche une invite de confirmation avant de continuer.

Ouvrir un plan enregistré à partir de l’éditeur

  1. Ouvrez un onglet d’éditeur qui contient la sortie PostgreSQL EXPLAIN au format JSON ou TEXT.
  2. Ouvrez la palette de commandes (Ctrl+Maj+P).
  3. Exécuter PGSQL : visualiser le plan de requête à partir de l’éditeur.
  4. Passez en revue le plan importé dans le visualiseur.

Ce flux de travail ne nécessite pas de connexion de base de données active. La commande lit le contenu actuel de l’éditeur ; vous pouvez donc l’utiliser avec une sortie de plan copiée, des fichiers .json ou .txt enregistrés, ou du texte de plan collé dans un éditeur temporaire.

Basculer entre les vues

Utilisez le sélecteur d’affichage dans la barre d’outils pour vous déplacer entre l’arborescence, l’affichage Icicle, la vue Table et la vue source.

Arborescence

L’arborescence s’ouvre par défaut. Utilisez-le lorsque vous souhaitez un diagramme de nœud par nœud du plan d’exécution.

  • Utilisez les contrôles de zoom pour effectuer un zoom avant, effectuer un zoom arrière, réinitialiser la vue ou ajuster le plan à la fenêtre.
  • Utilisez le panneau d’options pour modifier la direction de la disposition et la métrique de couleur qui met en évidence les nœuds coûteux ou inhabituels.
  • Sélectionnez un nœud pour ouvrir le volet d’informations.
  • Cliquez avec le bouton droit sur un nœud pour accéder à une autre vue ou analyser ce nœud avec l’Assistant IA.

Affichage en tableau

Utilisez la vue Table lorsque vous souhaitez trier, rechercher et comparer plusieurs nœuds à la fois.

  • Le plan est converti en tableau triable plutôt qu’en arborescence repliable.
  • La zone de recherche s’affiche uniquement en mode Tableau.
  • La recherche correspond au type de nœud, au nom de relation, au nom d’index, à l’alias, au texte de filtre et au nom du sous-plan.
  • Utilisez le sélecteur prédéfini pour vous concentrer sur les performances, les estimations, l’efficacité ou les E/S, ou personnaliser les colonnes de métrique visibles.

Vue Icicle

Utilisez la vue Icicle lorsque vous souhaitez obtenir un résumé visuel sur toute la largeur montrant où se concentrent les coûts, le temps ou l’utilisation de la mémoire tampon.

  • Icicle View est une vue distincte, et non un volet de Tree View.
  • Utilisez le panneau d’options pour passer d’un préréglage à l’autre, modifier la métrique de largeur, modifier la métrique de couleur et basculer entre la portée propre et la portée totale lorsque cette option est disponible.
  • Pointez sur un bloc pour inspecter ses métriques, ou cliquez avec le bouton droit sur un bloc pour ouvrir les détails ou passer à une autre vue.

Vue du code source

Utilisez la vue source lorsque vous souhaitez obtenir la sortie du plan d’origine.

  • Sélectionnez Options pour basculer entre l’arborescence et le mode texte .
  • Le panneau indique si la source importée ou générée est JSON ou TEXT.
  • Développez Tout et Réduire tout s’affichent dans la barre d’outils uniquement lorsque l’affichage source est actif.
  • En mode Texte , le plan s’ouvre dans un éditeur en lecture seule. En mode Arborescence, vous pouvez inspecter la structure analysée sous forme d’arborescence repliable.

Sélectionnez Copier le plan à tout moment pour copier la source du plan actuel dans le Presse-papiers. Les plans JSON sont copiés sous forme formatée et les plans TEXT sont copiés en tant que source d’origine.

Inspecter les nœuds du plan

Sélectionnez un nœud dans l’arborescence, la vue table ou l’affichage Icicle pour ouvrir le volet d’informations.

  • Général montre le type de nœud, les métriques clés et les détails d’analyse spécifiques au plan.
  • Les E/S s’affichent lorsque le plan inclut des données de mémoire tampon.
  • Les conditions s’affichent lorsque le nœud expose des filtres, des conditions de jointure ou des prédicats similaires.

Utilisez ce panneau pour comparer le travail estimé et le travail réel, examiner les nœuds gourmands en mémoire tampon et confirmer quels prédicats déterminent le plan.

Analyser des plans avec l’assistant IA

Utilisez l’Assistant IA lorsque vous souhaitez que l’extension ouvre une conversation d’analyse avec le plan actuel en tant que contexte.

Analyser le plan complet

  1. Ouvrez le plan dans le visualiseur.
  2. Sélectionnez Analyser avec Copilot (ou Analyser avec l’IA dans le curseur).
  3. Indiquez s’il faut inclure votre texte de requête SQL avec l’analyse.
  4. Passez en revue la nouvelle session de conversation qui s’ouvre en mode Agent.

Si le plan provient de PGSQL : visualiser le plan de requête à partir de l’éditeur et qu’il n’existe pas encore de texte SQL utile, l’extension peut vous inviter à entrer la requête en premier afin que l’IA ait un meilleur contexte.

Analyser un nœud

  1. Cliquez avec le bouton droit sur le nœud à inspecter.
  2. Sélectionnez Analyser ce nœud avec Copilot (ou analysez ce nœud avec l’IA dans le curseur).
  3. Passez en revue la nouvelle session de conversation en mode Agent pour une analyse spécifique au nœud.

Contrôler si le texte SQL est inclus

Le pgsql.copilot.autoAttachQuery paramètre contrôle la façon dont l’extension gère le texte SQL lorsqu’elle lance l’analyse ia :

  • Demander s’il faut inclure SQL à chaque fois
  • Toujours inclure SQL sans invite
  • N’incluez jamais SQL

Lorsque vous choisissez d’inclure ou d’exclure SQL de l’invite, l’extension peut également vous rappeler ce choix pour les sessions futures.

Utiliser l’outil de plan de requête en mode Agent

Le visualiseur met en cache le plan actuel et le met à la disposition de l’assistant IA via l’outil pgsql_query_plan, ou son équivalent MCP sur les hôtes pris en charge. Cet outil prend en charge ces actions :

Action Utilisez-le pour
get_summary Obtenez un résumé à l’échelle du plan avant d’explorer les détails.
get_node Inspectez un nœud par ID.
get_subtree Inspectez un nœud ainsi que ses descendants.
list_nodes Recherchez des nœuds par type ou coût minimal.

Si vous souhaitez que l’IA démarre à partir de la requête active au lieu du visualiseur, utilisez le sous-menu Analyser les performances des requêtes à partir du sous-menu Actions de requête IA de l’éditeur. Utilisez le visualiseur lorsque vous souhaitez inspecter le plan vous-même, puis passez ce plan exact à l’IA.

Conseils pour l’analyse des performances

  • Utilisez ANALYZE quand il est sûr d’exécuter l’instruction. Les estimations seules peuvent masquer les hypothèses de nombre de lignes incorrectes.
  • Comparez les nombres de lignes estimés et réels pour repérer les statistiques obsolètes ou les problèmes de sélection de filtre.
  • Basculez vers la vue Tableau lorsque le plan est volumineux et que vous avez besoin d’effectuer des recherches ou de comparer les métriques côte à côte.
  • Basculez vers la vue source lorsque vous avez besoin du plan brut pour un problème, une révision de code ou une discussion avec vos collègues.

Contenu connexe

  • Last updated on