PostgreSQL 拡張機能のクエリ プラン ビジュアライザーを使用して、エディターを終了せずに PostgreSQL EXPLAIN 出力を検査します。 クエリ エディターまたは PostgreSQL クエリ結果パネルからプランを生成するか、エディターから既存の JSON または TEXT プランの出力を開くことができます。 ビジュアライザーは、Visual Studio Codeと Cursor で同じように実行されます。
前提条件
- PostgreSQL 拡張機能 がインストールされています。
- クエリ エディターまたは PostgreSQL クエリ結果パネルからライブ プランを生成する場合は、PostgreSQL サーバーへのアクティブな接続。
- AI 支援分析が必要な場合は、オプションの AI アシスタントを使用します。Visual Studio CodeにGitHub Copilotをインストールするか、Cursor で組み込みの AI を使用します。
- データベースに接続せずに保存したプランをインポートする場合は、オプションの
EXPLAIN出力がエディターで既に開いています。
プランを開く方法を選択する
ワークフローに一致するエントリ ポイントを使用します。
- クエリ エディター: エディター ツール バーの [ クエリ プランの視覚化 (PostgreSQL)] を選択します。 最初にテキストを選択しない場合、拡張機能は現在のエディターの内容を使用します。
- [PostgreSQL クエリ結果] パネル: クエリを実行し、[PostgreSQL クエリ結果] パネルのツール バーで [ クエリ プランの視覚化 ] を選択して、その結果セットを生成したクエリを検査します。
- インポートされたプラン: PostgreSQL プランの出力を含むエディター タブを開き、コマンド パレットから PGSQL: Visualize Query Plan from Editor を実行します。
ライブ クエリからプランを生成する
- クエリ エディターで、検査する SQL ファイルを開きます。
- ターゲット データベースに接続します。
- 分析するステートメントを選択します。 選択範囲を空のままにすると、拡張機能は現在のエディターの内容を使用します。
- エディター ツール バーの [ クエリ プランの視覚化 (PostgreSQL)] を選択します。 最初にクエリを実行し、[PostgreSQL クエリ結果] パネルで [クエリ プランの視覚化] を選択することもできます。
- [ クエリ プランの構成] で、目的の形式とオプションを選択し、Enter キーを押します。
- ビジュアライザーでプランを確認します。
クエリ プラン のオプションを構成する
[クエリ プランの構成] ピッカーでは、実行する出力形式とEXPLAINオプションを選択できます。
| Option | 変更内容 |
|---|---|
| JSON | ビジュアル ビュー全体で最適に動作する構造化されたプランの出力を返します。 |
| TEXT | PostgreSQL のプレーンテキスト EXPLAIN 出力を返し、 ソース ビューでそのソースを保持します。 |
| 分析 | クエリを実行し、実際の実行時統計を含みます。 |
| バッファー | バッファー使用量の統計情報を追加します。 これを自動的に選択すると 、ANALYZE が有効になります。 |
| タイミング | 実際のタイミング データを追加します。 これを自動的に選択すると 、ANALYZE が有効になります。 |
| Wal | WAL の使用状況統計を追加します。 これを自動的に選択すると 、ANALYZE が有効になります。 |
| VERBOSE | スキーマや列の情報などの追加の出力の詳細を追加します。 |
| コスト | 推定スタートアップと合計コストの値が含まれます。 |
| 設定 | 既定値とは異なるプランナー設定が含まれます。 |
Caution
EXPLAIN ANALYZE はクエリを実行します。 ステートメントでデータ ( INSERT、 UPDATE、 DELETE、 TRUNCATEなど) を変更すると、続行する前に確認プロンプトが表示されます。
エディターから保存したプランを開く
- JSON または TEXT 形式の PostgreSQL
EXPLAIN出力を含むエディター タブを開きます。 - コマンド パレットを開きます (Ctrl + Shift + P)。
- PGSQL を実行する: エディターからクエリ プランを視覚化します。
- ビジュアライザーでインポートされたプランを確認します。
このワークフローでは、アクティブなデータベース接続は必要ありません。 このコマンドは現在のエディターの内容を読み取るので、コピーしたプランの出力、 .json または .txt ファイルの保存、またはスクラッチ エディターに貼り付けたプラン テキストで使用できます。
ビューを切り替える
ツール バーのビュー セレクターを使用して、 ツリー ビュー、 Icicle ビュー、 テーブル ビュー、 およびソース ビューの間を移動します。
ツリービュー
ツリー ビュー が既定で開きます。 実行プランのノードごとの図が必要な場合に使用します。
- ズーム コントロールを使用して、拡大、縮小、ビューのリセット、またはプランをウィンドウに合わせて調整します。
- オプション パネルを使用して、レイアウトの方向と、高価なノードや通常とは異なるノードを強調表示するカラー メトリックを変更します。
- ノードを選択して詳細パネルを開きます。
- ノードを右クリックして別のビューに移動するか、AI アシスタントを使用してそのノードを分析します。
テーブル ビュー
一度に多数のノードを並べ替え、検索、比較する場合は、 テーブル ビュー を使用します。
- プランは、折りたたみ式ツリーではなく、並べ替え可能なテーブル形式に変換されます。
- 検索ボックスは テーブル ビューにのみ表示されます。
- 検索は、ノードの種類、関係名、インデックス名、エイリアス、フィルター テキスト、サブプラン名と一致します。
- プリセット選択機能を使用して、 パフォーマンス、 見積もり、 効率、または I/O に重点を置くか、表示されるメトリック列をカスタマイズします。
Icicle ビュー
コスト、時間、またはバッファーの使用量が集中している場所を全幅の視覚的な概要で表示する場合は、 Icicle ビュー を使用します。
- Icicle ビュー は別のビューであり、 ツリー ビュー内のペインではありません。
- オプション パネルを使用して、プリセットの切り替え、幅メトリックの変更、カラー メトリックの変更、サポートされている自己スコープと合計スコープの切り替えを行います。
- ブロックにカーソルを合わせてメトリックを調べるか、ブロックを右クリックして詳細を開くか、別のビューに移動します。
ソースビュー
元のプラン出力が必要な場合は、 ソース ビュー を使用します。
- ツリーモードとテキストモードを切り替えるには、[オプション] を選択します。
- パネルには、インポートされたソースまたは生成されたソースが JSON か TEXT かを示します。
- [すべて展開] と [すべて折りたたむ ] は、 ソース ビュー がアクティブな場合にのみツール バーに表示されます。
- テキスト モードでは、プランが読み取り専用エディターで開きます。 ツリー モードでは、解析された構造を折りたたみ可能なツリーとして検査できます。
現在の プラン ソースをクリップボードにコピーするには、いつでも [プランのコピー] を選択します。 JSON プランは書式設定された形式でコピーされ、TEXT プランは元のソースとしてコピーされます。
プランノードを確認する
ツリー ビュー、テーブル ビュー、または Icicleビューでノードを選択して、詳細パネルを開きます。
- 全般 には、ノードの種類、主要なメトリック、およびプラン固有の分析の詳細が表示されます。
- I/O は、プランにバッファー データが含まれている場合に表示されます。
- 条件 は、ノードがフィルター、結合条件、または同様の述語を公開するときに表示されます。
このパネルでは、見積もり作業量と実際の作業量を比較し、バッファ使用量の多いノードを調べ、どの述語がプランを左右しているかを確認できます。
AI アシスタントを使用して計画を分析する
拡張機能で現在のプランをコンテキストとして分析チャットを開く場合は、AI アシスタントを使用します。
完全なプランを分析する
- ビジュアライザーでプランを開きます。
- Copilotで分析 (またはカーソル内の AI を使用して分析) を選択します。
- 分析に SQL クエリ テキストを含めるかどうかを選択します。
- エージェント モードで開く新しいチャット セッションを確認します。
プランが PGSQL から来た場合 : エディターからクエリ プランを視覚化 し、有用な SQL テキストがまだない場合は、拡張機能で最初にクエリを入力するように求められるので、AI のコンテキストが向上します。
1 つのノードを分析する
- 検査するノードを右クリックします。
- Copilotを使用してこのノードを分析する (またはカーソル内の AI を使用してこのノードを分析する) を選択します。
- ノード固有の分析について、新しいエージェント モードのチャット セッションを確認します。
SQL テキストを含めるかどうかを制御する
pgsql.copilot.autoAttachQuery設定は、拡張機能が AI 分析を起動するときに SQL テキストを処理する方法を制御します。
- 毎回 SQL を含めるかどうかを確認する
- プロンプトを表示せずに常に SQL を含める
- SQL を含めない
プロンプトに SQL を含めるか、またはプロンプトから除外するかを選択した場合、拡張機能は今後のセッションでその選択を覚えておくこともできます。
エージェント モードでクエリ プラン ツールを使用する
ビジュアライザーは、現在のプランをキャッシュし、 pgsql_query_plan ツールを使用して AI アシスタントに公開するか、サポートされているホストで同等の MCP を公開します。 このツールでは、次のアクションがサポートされます。
| アクション | これを次の目的に使用します。 |
|---|---|
get_summary |
詳細を詳しく調べる前に、プラン全体の概要を取得します。 |
get_node |
1 つのノードを ID で調べます。 |
get_subtree |
ノードとその子孫を検査します。 |
list_nodes |
種類または最小コストでノードを検索します。 |
ビジュアライザーではなくアクティブなクエリから AI を開始する場合は、エディターの AI クエリ アクション サブメニューからクエリ パフォーマンスの分析を使用します。 最初に自分で計画を検査し、その正確な計画を AI に渡す場合は、ビジュアライザーを使用します。
パフォーマンス分析のヒント
- ステートメントを安全に実行できる場合は、 ANALYZE を使用します。 推定値だけでは、行数についての誤った前提が覆い隠される可能性があります。
- 推定行数と実際の行数を比較して、古い統計を特定したり、選択度の問題をフィルター処理したりします。
- プランが大きく、検索または並列メトリック比較が必要な場合は、 テーブル ビュー に切り替えます。
- 問題、コード レビュー、またはチームメイトとのディスカッションに生の計画が必要な場合は、 ソース ビュー に切り替えます。