postgres-diagnostics

pgbot による PostgreSQL の診断

pgbot は読み取り専用の Postgres 診断ツールです。診断結果は（モデルではなく Go で）決定論的に算出され、データベースに書き込むことは一切ありません。pgbot の出力を信頼できる情報源として扱ってください。適切なコマンドを実行し、その結果を解釈して優先順位を付け、推奨事項を提示するのがあなたの役割です。診断をでっち上げたり、データベースに対して操作を行ったりしてはいけません。

このスキルを使用する場面

• 「データベースが遅いのはなぜ？」「何を最適化すればいい？」「DB は正常？」
• 「削除できるインデックスはどれ？」「ディスクを使い切っているのは何？」「autovacuum は追いついている？」
• 「データベースを圧迫しているクエリは何？」「設定を再調整すべき？」
• PostgreSQL のパフォーマンス／健全性／肥大化／インデックス／バキューム／設定に関する質問全般。

実行方法

pgbot MCP サーバーが接続されている場合は、そのツールを呼び出します。inspect（ここから始めます）、top_queries、vacuum_health、unused_indexes、why を使用してください。これらは安定した JSON を返します。 （logs、waits、activity、erd、report コマンドは、現時点では CLI 専用です。シェル経由で実行してください。）

それ以外の場合は CLI を実行します。 読み取り可能なロールの接続文字列が必要です（可能であれば pg_monitor を持つロールを使用してください）。質問に合ったコマンドを選んでください。

質問	コマンド
自由形式／「正常？」	pgbot inspect "$DSN"（健全性スコア＋問題の深刻度が高い順の診断結果）
詳細全般	pgbot inspect "$DSN" --full
「データベースを圧迫しているのは何？」	pgbot queries "$DSN"（合計時間が長い順。順位を付け直すには --by-calls）
「ディスクを使っているのは何？／最大のテーブルは？」	pgbot tables "$DSN"（サイズ＋シーケンシャルスキャンとインデックススキャンの比較＝インデックス欠落の手がかり）
「autovacuum は追いついている？」	pgbot vacuum "$DSN"
「削除できるインデックスはどれ？」	pgbot indexes "$DSN"
「設定を再調整すべき？」	pgbot tune "$DSN"
「今、遅いのはなぜ？」	pgbot why --duration 10s "$DSN"（稼働中の待機をサンプリングし、証拠に基づいて原因を特定します。ロック競合、I/O、CPU、クライアントのいずれかを判定し、証拠が不十分な場合は推測を拒否します）
「接続中のユーザーは？／実行中の処理は？」	pgbot activity "$DSN"（稼働中のセッション：PID、状態、待機、経過時間、機密情報を除去した SQL）
「データベースの時間はどこで使われている？」	pgbot waits --duration 10s "$DSN"（待機クラスをサンプリングし、継続的な証拠がある場合に限ってブロッカーを特定します）
「昨日から何が変わった？」	pgbot why "$DSN" ／ pgbot diff --since 24h（保存済みスナップショットを使ったオフライン分析）
「サーバーログには何が記録されている？」	pgbot logs "$DSN"（追跡するには --live、絞り込むには --level error または --level audit を指定します。不足している場合は、追加で必要な権限を表示します）
「スキーマはどんな構成？」	pgbot erd "$DSN"（表示可能な図を生成するには --mermaid、インタラクティブなファイルを作成するには --html > schema.html）
人が読むための完全なレポート	pgbot report "$DSN" > report.html（診断結果、クエリ、インデックス、待機を含む自己完結型ページ）
パース用の機械可読形式	pgbot inspect "$DSN" --json

大規模なデータベースまたはリモートデータベースの場合は、--timeout 60s を追加します。

初回実行 — 前提条件が不足している場合

手を止めたり、その場しのぎで対応したりしないでください。不足している条件には、それぞれ対処方法があります。

• pgbot が PATH にない場合： インストールします — curl -fsSL https://pgbot.dev/install | sh （または brew install pgrundev/tap/pgbot、あるいはインストールせずに npx @pgbot/cli を実行します）。通常の権限確認プロンプトを通して実行し、ユーザーにコマンドを確認してもらってください。
• 接続文字列がない場合： $DATABASE_URL を確認し、それからユーザーに接続文字列を尋ねます。 認証情報を推測したり、自分で組み立てたりしてはいけません。
• ロールまたは拡張機能が不足している場合： インストール済みの pgbot に init がある場合は、 pgbot init --verify "$DSN" を実行します。これは pg_monitor と pg_stat_statements を確認し、 個別の対処方法を示します。古いビルドでは、接続時に同じ不足項目が報告されます。 読み取り専用ロールを作成するには、pgbot init で SQL を生成するか、pgbot README の Setup セクションを使用し、 SQL を管理者として実行するようユーザーに渡してください。自分で実行してはいけません。pgbot は一切書き込みを行わず、あなたも書き込みを行わないでください。

ルール — 絶対に守ること

1. 検出結果は事実です。 pgbot が報告した内容を超えて、数値、テーブル、インデックス、クエリ ID を作り出さないでください。pgbot が測定していない場合は、確認するために pgbot が何を収集する必要があるかを述べてください。
2. 推奨事項には、あらゆる注意事項を必ず含めてください。 例：「未使用インデックス」のスキャン件数はノードごとの集計です。プライマリで未使用に見えるインデックスでも、レプリカでは使用されている可能性があります。pgbot はこれを警告します。注意事項を添えずにインデックスの削除を推奨してはいけません。（pgbot の tables／indexes と JSON にはレプリケーションの状態が表示されます。確認してください。）
3. 診断のためにユーザーのクエリを実行してはいけません。 EXPLAIN ANALYZE も、実行時間を測るためだけにステートメントを実行することも禁止です。実行を伴わない安全な手順のみを提案してください（ANALYZE なしの EXPLAIN はクエリを実行しないため問題ありません）。
4. 件数ではなく影響度で優先順位を付けてください。 リスク（トランザクション ID の周回、WAL を保持し続けるレプリケーションスロット、ディスク容量の枯渇など、インシデント発生までの時間）が最優先です。次に、レイテンシーやストレージの改善幅が最大の項目を扱います。未使用インデックスの 9 GiB 分の回収より、DB 時間の 60% を消費するクエリ 1 件のほうが重要な場合があります。何を先に行うべきか、その理由とともに述べてください。
5. データベースに書き込んではいけません。 pgbot は読み取り専用です。あなたは推奨するだけで、実行はしません。ユーザー自身が実行できる、正確な DROP INDEX CONCURRENTLY／ALTER／VACUUM ステートメントを提示してください。
6. 確信度が低い場合は断定を避けてください。 確信度が 0.5 未満の検出結果は断定ではなく、「可能性がある」「おそらく」などの表現にしてください。
7. 根拠を明記してください。 回答では、pgbot のデータで証明された検出結果、（コード、レプリカ、またはワークロードの）レビューが必要な推奨事項、統計情報または権限の不足により結論を出せない項目の 3 つを、明確に区別してください。

出力形式

1. 健全性の評価を 1 行で示します。
2. 影響の大きい順に、問題を最大約 3 件挙げます。それぞれ、問題点（pgbot の数値を含む）→ データ（差分／イベント）が裏付けている場合に限り、考えられる原因 → 注意事項を併記した安全で具体的な推奨手順を示します。
3. 何が健全だったかを簡潔に挙げ、何を確認したかがユーザーに伝わるようにします。

シグナルの読み取り方

• tables: シーケンシャルスキャンが多く、インデックススキャンが少ない大きなテーブルは、インデックス不足の候補です。queries と照合してください。そのテーブルをフィルタリングする上位クエリがあれば、候補であることが確認できます。
• queries: share は DB の総実行時間に占める割合です。単一クエリが約 30% を超えている場合、それが実際のホットパスです。インデックスの削除では改善しません。
• vacuum: due? yes で、最終自動バキュームが古い、または never の場合、自動バキュームが遅れています。これはテーブルの肥大化、ひいてはトランザクション ID の周回が発生する前兆です。
• レプリケーションスロットの検出結果: 非アクティブなスロットが WAL を保持し続けると、ディスク容量が枯渇します。見た目だけの問題ではなく、インシデント発生までの時間に関わる問題として扱ってください。

安全性とプライバシー

pgbot は常に読み取りのみを行います。マシン外へ送信されるのは pgbot explain／pgbot ask のみで、これらは PII を含まない検出結果（リテラルを含まない正規化済みクエリテキスト）を LLM に送信するものであり、その旨が事前に通知されます。pg_monitor 権限を持つロールを使用してください。漏えいするおそれのある場所に、本番環境のスーパーユーザー認証情報を貼り付けないでください。