slowplan

slowplan：この PostgreSQL クエリはなぜ遅いのか？

PostgreSQL の EXPLAIN 出力を読み取り、どこに時間がかかっているのか、最初に何を試すべきかを教えてくれる MCP サーバーと CLI です。プランのテキストだけで動作するため、データベースに接続することはありません。

長い EXPLAIN ANALYZE は読みづらく、判断を誤りやすいものです。Postgres は並列プランではワーカーごとの平均を報告し、最も遅そうに見えるノードが実際に時間を費やした箇所とは限りません。slowplan は各ステップの実際の所要時間を算出し、行を大量に捨てるシーケンシャルスキャン、誤った行数推定、ディスクにあふれるソートやハッシュ、何度も実行されるネステッドループといった問題を優先度順に示します。

エージェントに質問できること

• 「この Postgres クエリは遅いです。EXPLAIN ANALYZE の出力はこちらです。」
• 「ここでプランナーがシーケンシャルスキャンを使うのはなぜですか？」
• 「インデックスを追加しました。効果はありましたか？」
• 「このプランで最初に修正すべき点は何ですか？」

インストール

Claude Code プラグインとして：

claude plugin marketplace add GillMacedo/slowplan
claude plugin install slowplan@slowplan-marketplace

任意のクライアントで使える MCP サーバーとして：

{"mcpServers": {"slowplan": {"command": "npx", "args": ["-y", "[email protected]", "serve"]}}}

Node 18 以降を使う CLI として：

npx slowplan review plan.txt

または Go 1.27 以降の場合：go install github.com/GillMacedo/slowplan@latest。

使い方

EXPLAIN (ANALYZE, BUFFERS) <your query> で、テキスト形式または JSON 形式のプランを取得します。**ANALYZE は実際にクエリを実行するため、**書き込みを行うクエリは必ずロールバックするトランザクションで囲んでください。

PostgreSQL 17 で、架空のテーブルを使って取得した実際のプランの例です：

$ make demo
実行 48.9 ms、計画 0.3 ms

時間の内訳：
   80.8%      39.5 ms  Bitmap Heap Scan on orders
    3.9%       1.9 ms  Bitmap Index Scan on orders_status_idx

HIGH   PG102 orders の Bitmap Heap Scan
  インデックスがフィルター全体をカバーしていません。84857 行を読み捨て、857 行を残しています。フィルターには (bucket = 7) が使われています。
  試すこと：検証候補：CREATE INDEX CONCURRENTLY ON orders (bucket)、または現在使われているインデックスにこれらの列を追加してください。

これらは一度の実行から得られた手掛かりです。修正を信頼する前に、現実的なデータでテストしてください。

変更を確認するには、変更前と変更後のプランを比較します：

slowplan compare before.txt after.txt

examples/ にある実際の例では、slowplan が提案したインデックスを追加したことで、クエリの実行時間が約 25 ms から 0.1 ms に短縮されました。

JSON 形式にするには --json を、CI で終了コード 1 を返すには --fail-on high を追加します。標準入力から読み込むには - を使います。

検出できる問題

ルール	検出内容
PG101	読み込んだ行の大半を捨てるシーケンシャルスキャン
PG102	フィルター全体をカバーしていないインデックス
PG103	行を生成した後にそれらを捨てる結合
PG104	多数の行を捨てるビットマップ再チェック
PG105	行数の推定が実際と10倍以上異なる状態
PG106	ネステッドループの内側が1,000回以上実行される状態
PG107	ディスクにあふれるソート
PG108	ハッシュテーブルがディスク上で複数のバッチに分割される状態
PG109	計画よりも並列ワーカーが少ない状態
PG110	インデックスオンリースキャンでも頻繁にテーブルを参照する状態
PG111	ビットマップがロッシーになった状態
PG112	共有バッファーの外部から約 80 MB 以上を読み込む状態
PG113	クエリの実行より計画に時間がかかる状態
PG114	JIT に100 ms 以上かかる状態

重大度はクエリ全体の時間に占める割合で決まります。高は20%以上、低は5%未満、または1 ms 未満です。これらのしきい値は判断に基づくものです。

MCP ツール

ツール	内容
postgres_plan_review	テキストまたはファイルから単一のプランをレビューします
postgres_plan_compare	変更前と変更後のプランを比較します

制限事項

• 推奨インデックスは候補にすぎません。 プランに表示されるのは、1つのクエリと1組の値であり、ほかのインデックスや書き込み時のインデックスのコストは考慮されません。実際のデータに近い条件でテストしてください。
• 1回の実行ではベンチマークになりません。 キャッシュの状態やサーバーの負荷によって、実行時間は変わります。
• プランからは ロック、ネットワーク時間、プラン外の要因は確認できません。推定値だけのプランには実測値がなく、slowplan はそのことを示します。
• 並列プランの実行時間は推定値です。 Postgres はワーカー間の平均値を報告するためです。
• PostgreSQL 専用です。他のツールのテキストプランや、大幅に編集されたプランは解析できない場合があります。JSON が最も確実です。
• プランにはクエリの値が含まれる場合があります。slowplan はお使いのマシン上で動作しますが、MCP クライアントはツールの結果をモデルに送信します。

よくある質問

EXPLAIN ANALYZE の出力はどう読み取ればよいですか？ slowplan に渡してください。処理時間の内訳が表示されます。

Postgres がシーケンシャルスキャンを実行するのはなぜですか？ 役立つインデックスがない場合や、フィルターに該当する行が多く、インデックスを使っても効果がない場合がよくあります。PG101 では、除外された行数が表示されます。

ソートやハッシュ処理がディスクを使用しているかどうかは、どうすればわかりますか？ PG107 と PG108 で確認できます。

pev2 や postgres-mcp とはどう違いますか？ pev2 は人向けのビジュアライザーです。postgres-mcp は稼働中のデータベースに接続します。slowplan はデータベースにアクセスせず、プランテキストからエージェント向けに優先順位を付けた分析結果を提示します。

テスト済み環境

PG101、PG102、PG104 から PG112 は、PostgreSQL 17 データベースから取得した実際のプランで動作確認済みです。使用したテーブルは架空のもので、JSON 形式とテキスト形式の両方が examples/ にあります。PG103、PG113、PG114 は、作成した例でのみテストしています。MCP ツールの呼び出しは MCP Inspector 経由でテスト済みです。実運用のクエリではまだ使用されていません。

貢献

個人の方も、AI エージェントと協業している方も、貢献を歓迎します。CONTRIBUTING.md をご覧ください。初めて取り組むのに適した課題はこちらに一覧があります。

プルリクエストの流れ

1. PR を作成します。 リポジトリをフォークし、ブランチで作業して、変更は1つに絞ってください。ユーザーにとって何が変わるのかを示すタイトルを付けてください。タイトルは変更履歴の項目になるため、feat: は Added、fix: は Fixed に分類されます。
2. 自動チェック。 コードの変更にはテストが必要で、make test が成功しなければなりません。30行を超える変更には、関連する未クローズの課題（Closes #<number>）が必要です。また、PR の変更行数は最大800行です。不足がある場合は、修正内容を示すコメントが投稿されます。
3. レビュー。 Claude が各 PR を自動的にレビューします。コードの PR にはセキュリティレビューも実施され、サンドボックスでテストされます。その後、レビューによって PR がマージされるか、修正が求められます。CI、エージェント設定、npm または Python の依存関係、ベンダーコード、ビルドファイルを変更する PR はこの方法ではマージできず、その旨がコメントで通知されます。セキュリティレビューで承認されなかったものも同様です。
4. リリース。 ユーザーがインストールするものを変更するマージは、約2時間以内に新しいバージョンとしてリリースされます。GitHub Release と、プロジェクトにある場合は npm パッケージも公開されます。ドキュメントと CI の変更は、次回のリリースまで保留されます。

AI に関する開示

このプロジェクトは主に Claude Code で生成され、メンテナーによるレビューを受けています。

自己紹介

私は Giulliano Macedo です。GoTech Solutions で開発者向けツールを作っています。最新情報を確認したり、連絡したりするには、以下をご覧ください。

• GitHub：GillMacedo
• LinkedIn：giulliano
• X：@giumacedo

slowplan が遅いクエリを見つけるのに役立ったら、スターを付けていただけると、ほかの人にも見つけてもらいやすくなります。

---

Giulliano Macedo、GoTech Solutions が開発 · LinkedIn · X