================================================================
 SQLpgEX  Version 1.0.0.1
 PostgreSQL 実行計画ビューア
                                        Copyright (C) Miyacode
================================================================

このたびは SQLpgEX をダウンロードいただきありがとうございます。
本書は SQLpgEX の使い方をまとめたユーザーマニュアルです。


■ 目次

  1. SQLpgEX とは
  2. 動作環境
  3. インストールとアンインストール
  4. まず動かしてみる(1分)
  5. EXPLAIN を読み込む3つの方法
  6. 画面の見方
  7. アドバイス機能について
  8. 困ったときは
  9. 制限事項
 10. 利用条件
 11. 更新履歴
 12. 連絡先


■ 1. SQLpgEX とは

SQLpgEX は、PostgreSQL の EXPLAIN / EXPLAIN ANALYZE の結果を読み
込み、実行計画をツリーと図で表示する Windows 用フリーソフトです。

EXPLAIN の出力はテキストのままでも読めますが、階層が深くなると
親子関係を追うだけでひと苦労です。SQLpgEX に貼り付ければ、実行
計画の構造がツリーとカード図で一目で分かり、時間のかかっている
ノードや、インデックスを検討すべき箇所の見当を付けられます。

Seq Scan や Sort といった代表的なノードには、確認すべきポイント
を日本語で表示します。SQL チューニングを自動で行うものではあり
ませんが、実行計画を読み解く最初の手掛かりとして使えます。

PostgreSQL サーバーへの接続は行いません。EXPLAIN の結果テキスト
さえあれば、DB に接続できない環境でも使えます。


■ 2. 動作環境

  対応 OS     : Windows 10 / Windows 11 (64bit)
  必要ソフト  : 特になし
  対応入力    : PostgreSQL のテキスト形式 EXPLAIN / EXPLAIN ANALYZE
                (ANALYZE, BUFFERS, VERBOSE, SETTINGS, SUMMARY を
                 含む出力に対応)

起動時にエラーが表示される場合は、Microsoft の
「Visual C++ 再頒布可能パッケージ (x64)」をインストールしてから
再度お試しください。


■ 3. インストールとアンインストール

インストール作業は不要です。ダウンロードした ZIP を任意のフォル
ダに解凍し、SQLpgEX.exe を実行してください。

アンインストールは、解凍したフォルダごと削除するだけです。通常
の使用ではレジストリへの書き込みは行いません。


■ 4. まず動かしてみる(1分)

手元に EXPLAIN の結果がなくても動作を確認できます。

  1. SQLpgEX.exe を起動します。
  2. 画面右上の「サンプル」ボタンを押します。

内蔵のサンプル実行計画が読み込まれ、左にツリー、右にカード図、
下に詳細と総評が表示されます。まずこの画面で、ノードをクリック
すると表示が切り替わることを確かめてみてください。


■ 5. EXPLAIN を読み込む3つの方法

PostgreSQL 側では、psql や pgAdmin などで次のように実行して結果
テキストを用意します。

  EXPLAIN ANALYZE SELECT ...;

より詳しい情報を見たい場合は、次の形がおすすめです。

  EXPLAIN (ANALYZE, BUFFERS, VERBOSE, SETTINGS, SUMMARY)
  SELECT ...;

用意したテキストは、次のいずれかの方法で読み込みます。

(1) 貼り付けて解析する
    「解析」ボタンを押すと EXPLAIN 入力ダイアログが開きます。
    結果テキストを貼り付けて OK を押してください。入力欄では
    Enter キーで改行できます。キャンセルを押すと、入力内容は
    破棄され、元の表示が維持されます。

(2) ファイルから開く
    「開く...」ボタン、またはメニューの「ファイル > 開く...」
    から、EXPLAIN 結果を保存したテキストファイル(.txt / .plan)
    を選びます。文字コードは UTF-8、Shift-JIS、UTF-16(BOM 付き)
    を自動判別します。

(3) サンプルを読み込む
    「サンプル」ボタンで内蔵サンプルを表示します。

EXPLAIN の結果であれば「QUERY PLAN」のヘッダー行や罫線が混ざっ
ていてもかまいません。自動的に読み飛ばします。


■ 6. 画面の見方

画面は1画面構成で、次の領域に分かれています。

  左側ツリー   : 実行計画の親子関係を階層表示します。
  右側カード図 : 各ノードをカードで表示し、親子を線で結びます。
  下部左(詳細) : 選択中ノードの数値と改善アドバイスを表示します。
  下部右(総評) : 実行計画全体の集計と確認ポイントを表示します。
  最下部       : 解析結果やエラーを表示するステータス欄です。

ツリーのノード名の後ろには、EXPLAIN ANALYZE の場合は実測時間と
実測行数が「[160.0 ms / rows=10]」の形で表示されます。ANALYZE
なしの EXPLAIN では「[推定rows=1000]」のように推定行数の表示に
なります。

ツリーとカード図はどちらをクリックしても連動して選択が切り替わ
り、詳細欄が更新されます。カード図は実行計画が大きい場合、右端
と下端のスクロールバーで表示範囲を移動できます。

詳細欄には選択中ノードについて次の情報が表示されます。

  ・cost(推定コスト)と rows (推定)
  ・actual time、rows (実測)、loops (EXPLAIN ANALYZE の場合)
  ・自ノード時間(子ノードの時間を除いた、このノード自身の時間)
  ・Filter、Index Cond、Sort Key などの注釈
  ・Buffers、Verbose Output(BUFFERS / VERBOSE 指定時)
  ・問題点と改善策のアドバイス

このうち「自ノード時間」が SQLpgEX の中心的な情報です。EXPLAIN
の actual time は子ノードの時間を含んだ累積値のため、そのまま見
ると親ノードほど大きく見えてしまいます。SQLpgEX は子ノード分を
差し引いた時間を計算し、本当に時間を使っているノードを判定に使
います。


■ 7. アドバイス機能について

選択中のノードに応じて、次のような観点のアドバイスを優先度
([高] [中] [低])付きで表示します。

  ・フィルタ付き Seq Scan に対するインデックス検討
  ・Sort に対する、並び順に合うインデックスの確認
  ・Hash Join / Nested Loop の結合に関する確認
  ・繰り返し回数(loops)が多いノードの注意
  ・自ノード時間が大きいノードのボトルネック指摘
  ・推定行数と実測行数が10倍以上ずれている場合の、統計情報
    更新(ANALYZE)の提案

アドバイスは簡易的なルールに基づく「確認ポイントの提示」です。
実際のチューニング判断は、実データ量、インデックス、統計情報、
SQL 全体を確認したうえで行ってください。


■ 8. 困ったときは

Q. 「ノードを解析できない」というエラーが出る
A. 入力が PostgreSQL のテキスト形式 EXPLAIN かを確認してくださ
   い。JSON 形式(FORMAT JSON)や、cost 表示のない出力
   (COSTS OFF)は解析できません。ノード行に (cost=...) が含ま
   れている必要があります。

Q. ファイルを開くと文字化けする
A. UTF-8、Shift-JIS、UTF-16(BOM 付き)は自動判別しますが、それ
   以外の文字コードの場合は、テキストエディタで UTF-8 として保
   存し直してから読み込んでください。

Q. Esc キーを押しても終了しない
A. 誤操作防止のため、Esc / Enter キーでは終了しない仕様です。
   終了は右上の閉じるボタン、または「ファイル > 終了」から行っ
   てください。

Q. 2つ目のウィンドウが開かない
A. 本ソフトは二重起動しない仕様です。すでに起動している場合は、
   既存のウィンドウが前面に表示されます。

Q. 画面が狭くて見づらい
A. ウィンドウの端をドラッグして広げると、各領域が自動的に再配
   置されます。


■ 9. 制限事項

  ・EXPLAIN (FORMAT JSON) には対応していません。
  ・COSTS OFF の出力には対応していません。
  ・PostgreSQL サーバーへ直接接続する機能はありません。
  ・読み込めるファイルサイズは 64MB までです。
  ・大きく整形・加工された EXPLAIN 出力は解析できない場合があ
    ります。
  ・メニューの「ライセンス登録」「ライセンス情報の表示」は、フ
    リーソフト版では無効化されています。異常ではありません。


■ 10. 利用条件

本ソフトはフリーソフトです。個人・企業を問わず無償で利用でき、
商用利用にあたって作者の許可は不要です。

本ソフトは無保証です。本ソフトを使用した結果生じたいかなる損害
についても、作者は責任を負いません。

作者の許可なく本ソフトを再配布することはできません。ただし、企
業・団体の内部で、取得した配布物をファイルサーバー等に置いて内
部の利用者にのみ配布することは問題ありません。

動作中のスクリーンショット画像・動画の取り扱いに制限はありませ
ん(画面に他者の著作物や機密情報が含まれる場合は、その取り扱い
規定に従ってください)。


■ 11. 更新履歴

  Version 1.0.0.1 (2026-07-27)
    ・初版公開
    ・PostgreSQL テキスト形式 EXPLAIN / EXPLAIN ANALYZE の解析
    ・実行計画のツリー表示とカード図表示
    ・選択ノードの詳細表示(推定/実測の区別、自ノード時間)
    ・簡易アドバイスと総評の表示
    ・ファイル読み込み(UTF-8 / Shift-JIS / UTF-16 自動判別)、
      貼り付け入力、内蔵サンプルに対応


■ 12. 連絡先

  作者   : Miyacode
  連絡先 : goldteru2fft@gmail.com

不具合のご報告の際は、お使いの Windows のバージョンと、可能であ
れば読み込ませた EXPLAIN テキストを添えていただけると助かります。

================================================================
