概要

Query-SenseはPostgreSQLのEXPLAIN / EXPLAIN ANALYZE出力を解析して、クエリ実行計画の問題点を検出し、実行可能な修正提案を返すツールです。CLIで動作し、JSON形式のEXPLAIN結果を渡すと、行数推定の誤差、シーケンシャルスキャンの検出、インデックス作成の提案、ANALYZEの推奨などを階層的にレポートします。開発者やDBAがボトルネックを素早く見つけ、優先度の高い対策を実行できるように設計されており、軽量なPythonパッケージとして配布されています。READMEの例では、1つのインデックスで2.3秒→0.04秒など大幅な改善を示すサンプルもあります。

リポジトリの統計情報

スター数: 18
フォーク数: 0
ウォッチャー数: 18
コミット数: 13
ファイル数: 7
メインの言語: Python

主な特徴

EXPLAIN / EXPLAIN ANALYZE（JSON）を解析して問題点を抽出し、わかりやすいメッセージと対処法を提示。
行推定誤差やシーケンシャルスキャン、統計情報不足（ANALYZE）やインデックス欠如を識別。
CLIツールとして簡単に導入可能（pip install querysense）、CIや運用スクリプトに組み込みやすい。
出力は重要度（CRITICAL, WARNING など）で分類され、優先対応が明確。

技術的なポイント

Query-Senseは主にPostgreSQLのEXPLAIN系出力（JSON形式）を入力として解析する点が技術的核です。ツールは実行計画ツリーを再帰的に走査し、各ノードの推定行数（plannerの推定値）と実際のスキャン行数（EXPLAIN ANALYZEで取得可能な実行統計）を比較して、行推定誤差を定量化します。大きな差が検出されると、推定誤差の原因として統計情報の古さ（ANALYZE不足）や結合順序・選択性の誤りを推定し、優先度付きで修復アクション（ANALYZEの実行、インデックス作成など）を提示します。

また、Seq Scanノードの検出では、スキャン対象テーブルの実行コストや行数を基に「インデックスで改善可能か」を推定し、想定される速度改善倍率（例: 57x）を提示します。インデックス提案は単純なカラム名と想定DDLを示す形で、実運用での導入前に手動検討が可能です。設計上は外部に接続してDBを操作するのではなく、EXPLAIN出力だけで推奨を生成するため、非侵襲でCI/CDやアラートパイプラインに組み込みやすくなっています。

実装はPythonパッケージ化され、CLIコマンド（querysense analyze）を提供。依存管理はpyproject.tomlで行われており、軽量で単機能を志向したコード構成のため、カスタマイズや拡張（新しいルールの追加、独自のコストモデル適用）も比較的容易です。READMEにある通り、典型的なワークフローはEXPLAIN ANALYZEのJSON出力を保存してからそれを解析する流れで、監視や自動診断のユースケースに適しています。

プロジェクトの構成

主要なファイルとディレクトリ：

.gitignore: file
README.md: file
pyproject.toml: file
query.png: file
scripts: dir

…他 2 ファイル

（README抜粋）

QuerySense

Analyze PostgreSQL EXPLAIN plans and get actionable performance fixes.

pip install querysense

```bash
$ querysense analyze slow_query.json

[CRITICAL] Row estimation error on orders (5,000x off)
   Planner estimated 50 rows, actually scanned 250,000.
   Fix: ANALYZE orders;

[WARNING] Sequential scan on orders (250,000 rows)
   Estimated improvement: 57x faster
   Fix: CREATE INDEX idx_orders_status ON orders(status);

QuerySense: 2.3s → 0.04s with one index

まとめ

EXPLAIN出力のみで実用的な改善案を出す、導入が容易なPostgreSQLパフォーマンス解析ツールです。（約50字）

Query-Sense — PostgreSQL EXPLAIN 解析ツール