Postgres AIops

Postgres AIops

免責事項：コミュニティが保守するオープンソースプロジェクトです。PostgreSQL Global Development Group またはいかなるベンダーとも提携、推奨、後援関係にありません。 「PostgreSQL」と象のロゴは PostgreSQL Community Association の商標です。すべての製品名および商標名は、それぞれの所有者に帰属します。MIT ライセンスです。

PostgreSQL DBA 運用のためのガバナンス付き AI 運用機能です。psycopg 3 でサーバーに接続し、システムカタログと pg_stat_* ビューを読み取ります。ガバナンス機能一式を内蔵しており、統合監査ログ、トークン／暴走実行予算ガード、取り消しトークンの記録、説明的なリスク階層ラベルを備えています。モックテストスイートに加え、読み取り、ガバナンス付き書き込み、およびその取り消しを、稼働中の PostgreSQL 16.14 インスタンスで検証済みです。詳細は docs/VERIFICATION.md をご覧ください。

できること

主要な分析機能を3つ備え、その周辺のガード付き読み取りと書き込みにも対応しています。

• スロークエリの根本原因分析 — pg_stat_statements の最も問題のあるエントリ（および任意の EXPLAIN プラン）を取得し、その数値（平均時間、キャッシュヒット率、一時領域へのスピル、呼び出し回数、プランノードの種類）を、根拠を示した原因と具体的な対処策に結び付けます。各分析結果には、ブラックボックス的な判定ではなく、測定値が含まれます。
• 肥大化とバキュームの分析 — テーブルごとのデッドタプル比率と自動バキュームの実施時期を組み合わせ、順位付けした根拠付きの推奨事項（VACUUM／自動バキュームの調整）を提示します。
• ブロッキングロックチェーンの根本原因分析 — pg_blocking_pids から待機ツリーを構築し、ルートブロッカー（ほかの処理をブロックし、自身は何も待っていない処理）を特定して、対処策を提示します。循環がある場合は、デッドロックの可能性が高いと報告します。

対応機能

• CLI（postgres-aiops ...）：init、overview、server、activity、query、index、table、repl、analyze、remediate、secret、doctor、mcp。
• MCP サーバー（postgres-aiops mcp または postgres-aiops-mcp）：35個のツール（読み取り25個、書き込み10個）に対応し、すべて組み込みの @governed_tool ハーネスでラップされています。
• 暗号化された認証情報：ロールのパスワードは、暗号化ストア ~/.postgres-aiops/secrets.enc（Fernet + scrypt）に保存され、ディスク上に平文で保存されることはありません。POSTGRES_AIOPS_MASTER_PASSWORD（MCP／CI）からマスターパスワードを取得するか、対話型プロンプト（CLI）で入力してロックを解除します。
• 可逆性：状態を変更する書き込みでは、実際の変更前の状態を最初に取得し、忠実な逆操作を記録します。create_index↔drop_index は相互に取り消し可能です。drop_index は pg_get_indexdef を取得するため、取り消し時にインデックスを正確に再作成できます。update_setting は変更前の値を取得するため、取り消し時に元の値に戻せます。不可逆な操作（terminate_backend、cancel_query、run_vacuum、run_analyze、reindex、reset_query_stats）は、監査用に変更前の統計を記録しますが、取り消し操作は宣言しません。
• 安全性：状態を変更するCLI操作はすべて --dry-run に対応し、二重確認が必要です。書き込みを行うMCPツールはすべて dry_run プレビューを受け取ります。パラメーター化できない識別子（テーブル名／インデックス名／GUC名）はすべて検証して引用符で囲み、すべての値はクエリパラメーターとしてバインドされます。

機能マトリクス（35 個の MCP ツール）

分野	ツール	数	R/W
概要	overview	1	読み取り
サーバー	server_version, show_settings, list_extensions, list_databases, list_roles	5	読み取り
アクティビティ	list_activity, long_running_queries, list_locks	3	読み取り
クエリ	top_queries, explain_query	2	読み取り
インデックス	unused_indexes, missing_index_hints, index_bloat, invalid_indexes	4	読み取り
テーブル	table_sizes, table_bloat, autovacuum_status	3	読み取り
レプリケーション	replication_status, replication_slots, wal_status	3	読み取り
分析（主力機能）	slow_query_rca, bloat_and_vacuum_analysis, blocking_lock_chain_rca	3	読み取り
書き込み	terminate_backend, cancel_query, drop_index	3	書き込み（高）
	run_vacuum, run_analyze, create_index, reindex, update_setting, reset_query_stats	6	書き込み（中）
取り消し	undo_list	1	読み取り
	undo_apply	1	書き込み（中）

主力の分析機能には、純粋なオフライン分析用のレコードを渡すことも、設定済みのターゲットからライブデータを取得させることもできます。top_queries／slow_query_rca には pg_stat_statements 拡張機能が必要です。読み取りロールには pg_monitor を付与してください。

このツールが判断すること、しないこと

このツールは、PostgreSQL DBA の操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続先アカウントの権限に委ねられます。書き込み権限のない PostgreSQL ロール（読み取り専用ロール、または INSERT／UPDATE／DELETE／DDL の権限を持たないロール）で接続すれば、実際に権限を管理する場所であるサーバー側で書き込みが失敗します。

そのため、設定する読み取り専用スイッチも、ポリシーファイルも、承認ゲートもありません。このツールが保証するのは、何も隠れて実行されないことです。MCP 経由でも CLI 経由でも、すべての呼び出しは監査行として ~/.postgres-aiops/audit.db に記録され、破壊的な書き込みでは実行前の状態も取得され、可能な場合は逆操作も記録されます。

各ツールは risk_level を宣言し、説明用の区分（none／confirm／review）として監査行に記録します。これにより、レビュー担当者は高リスクの削除だった行をひと目で確認できます。これはラベルであり、ゲートではありません。

より小規模なモデルやローカルモデルを実行していますか？agent-guardrails.md をご覧ください。このツールが現在代わりに適用するガードレール（プロンプトの予算を使って再指定する必要はありません）と、残りの内容に使えるすぐに利用可能なシステムプロンプトが記載されています。

クイックスタート

Claude Code プラグインとして

一度のインストールで、エージェントにスキルと MCP サーバーの両方が導入されます。

/plugin marketplace add AIops-tools/marketplace
/plugin install postgres-aiops@aiops-tools

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されます。そのため、監査行から、それを書き込んだコードを追跡できます。認証情報は引き続き postgres-aiops init で設定します。詳細は以下をご覧ください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されています。一度のインストールで、スキルと MCP サーバーをまとめて導入できます。

openclaw plugins install clawhub:@zw008/postgres-aiops
openclaw skills info postgres-aiops          # expect: Visible to model: yes

その後、プラグインを読み込ませるために OpenClaw ゲートウェイを再起動してください。MCP サーバーは uv で取得され、この特定のリリースに固定されるため、uvx が PATH に含まれている必要があります。uvx がない場合もスキルはインストールされますが、Visible to model: no と表示されます。認証情報は以下と同じ方法で設定します。

CLI またはスタンドアロン MCP サーバーとして

uv tool install postgres-aiops             # or: pipx install postgres-aiops
postgres-aiops init                        # wizard: add a target + store the password (encrypted)
postgres-aiops doctor                      # verify config, secrets, connectivity
postgres-aiops overview                    # one-shot cluster health snapshot
postgres-aiops analyze slow-query          # RCA the worst pg_stat_statements entry
postgres-aiops table bloat                 # dead-tuple bloat proxy per table

MCP サーバーとして実行します（stdio）。

export POSTGRES_AIOPS_MASTER_PASSWORD=...  # unlock secrets non-interactively
postgres-aiops-mcp

そのパスワードが保存される場所：エクスポートした変数は、このシェルが起動するすべてのプロセスから読み取り可能であり、シェルの履歴にも記録されます。共有ホストや長時間稼働するホストでは、対話型プロンプトを使うか、必要なコマンドの実行中だけシークレットマネージャーから渡すことをおすすめします。

ガバナンス

すべての MCP ツールは、同梱の @governed_tool ハーネスを経由します。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスクティア、オペレーターが指定した承認者／根拠がある場合はその内容）が ~/.postgres-aiops/audit.db に記録されます（POSTGRES_AIOPS_HOME で移動可能です）。CLI でも MCP の経路と同じレコードが書き込まれるため、監査されないエントリーポイントはありません。
• 暴走防止ガード — 認可ゲートではなく、安全性を確保するための最後の防壁です。同じ呼び出しが短時間に繰り返されると、サーキットブレーカーが作動します。POSTGRES_RUNAWAY_MAX=0 で無効にできます。必要に応じて、POSTGRES_MAX_TOOL_CALLS／POSTGRES_MAX_TOOL_SECONDS で厳格な上限を設定できます。
• 取り消し記録 — 元に戻せる書き込みでは、取得した変更前の状態に基づいて逆操作の記述子を記録します。
• リスクティア — risk_level から導出され、監査レコードに付与される説明用のラベルです。何も制限しません。

対象範囲

これは AIops-tools ファミリー（監査＋予算＋取り消し＋リスクティアを備えた、ガバナンス付きの AI オペレーション）の PostgreSQL DBA オペレーション向けメンバーです。OT／産業用エッジ（Modbus、OPC-UA、PROFINET）には使用しないでください。その場合は別系統の industrial-aiops を参照してください。また、アプリケーションスキーマのマイグレーションや ORM の管理にも使用しないでください。

必要な機能がありませんか？

このツールが対応するのは、PostgreSQL のカタログとメンテナンス機能のうち、意図的に選定された一部です。必要なビュー、メトリクス、またはメンテナンスコマンドがありませんか？ イシューまたは PR を作成してください。貢献を歓迎します。

ステータス

モックテストスイートに加えて、実環境での実行テストも行っています。Docker で動作する PostgreSQL 16.14 インスタンスに対して、カタログ／pg_stat_* の読み取り、bloat_and_vacuum_analysis の RCA、および create_index／drop_index のガバナンス付き書き込み経路（監査＋取り消し。drop_index では事前に pg_get_indexdef を取得）を検証しました。docs/VERIFICATION.md に、検証した項目と未検証の項目を正確に記載しています。実環境を最も手早く確認するには、postgres-aiops doctor を実行してください。