PostgreSQL performance Tuner MCP Server

PostgreSQL パフォーマンスチューニング MCP

AI を活用した PostgreSQL パフォーマンスチューニング機能を提供する Model Context Protocol (MCP) サーバーです。このサーバーは、低速なクエリの特定、最適なインデックスの推奨、実行プランの分析、および仮想インデックスのテストのための HypoPG の活用を支援します。

機能

クエリ分析

• pg_stat_statements から詳細な統計情報とともに低速クエリを取得
• EXPLAIN および EXPLAIN ANALYZE によるクエリ実行プランの分析
• 自動プラン分析によるパフォーマンスボトルネックの特定
• アクティブなクエリの監視と長時間実行トランザクションの検出

インデックスチューニング

• クエリワークロード分析に基づく AI によるインデックス推奨
• HypoPG 拡張機能による仮想インデックステスト（ディスク使用なし）
• クリーンアップのための未使用および重複インデックスの検出
• 作成前のインデックスサイズの見積もり
• 実装前に提案されたインデックスでクエリプランをテスト

データベースヘルス

• 複数のチェックによる包括的なヘルススコアリング
• 接続使用率の監視
• キャッシュヒット率の分析（バッファおよびインデックス）
• ロック競合の検出
• Vacuum の健全性とトランザクション ID の周回監視
• レプリケーション遅延の監視
• バックグラウンドライターおよびチェックポイントの分析

Vacuum 監視

• 長時間実行される VACUUM および VACUUM FULL 操作のリアルタイム追跡
• autovacuum の進捗とパフォーマンスの監視
• Vacuum が必要なテーブルの特定
• 最近の Vacuum アクティビティ履歴の表示
• autovacuum 設定の有効性の分析

I/O パフォーマンス分析

• テーブルおよびインデックス全体のディスク読み書きパターンの分析
• I/O ボトルネックとホットテーブルの特定
• バッファキャッシュヒット率の監視
• work_mem の問題を示す一時ファイル使用量の追跡
• チェックポイントおよびバックグラウンドライター I/O の分析
• PostgreSQL 16+ 拡張 pg_stat_io メトリクスのサポート

設定分析

• カテゴリ別の PostgreSQL 設定の確認
• メモリ、チェックポイント、WAL、autovacuum、接続設定に関する推奨事項の取得
• 最適でない設定の特定

MCP プロンプト & リソース

• 一般的なチューニングワークフロー向けの定義済みプロンプトテンプレート
• テーブル統計、インデックス情報、ヘルスチェック用の動的リソース
• 包括的なドキュメントリソース

インストール

標準インストール（Claude Desktop などの MCP クライアント向け）

pip install pgtuner_mcp

または uv を使用する場合:

uv pip install pgtuner_mcp

手動インストール

git clone https://github.com/isdaniel/pgtuner_mcp.git
cd pgtuner_mcp
pip install -e .

設定

環境変数

変数	説明	必須
DATABASE_URI	PostgreSQL 接続文字列	はい
PGTUNER_EXCLUDE_USERIDS	監視から除外するユーザー ID（OID）のカンマ区切りリスト	いいえ
PGTUNER_STATEMENT_TIMEOUT_MS	ステートメントごとのタイムアウト（ミリ秒、デフォルト 30000、0=無効）	いいえ
PGTUNER_IDLE_TXN_TIMEOUT_MS	トランザクション内アイドルのタイムアウト（ミリ秒、デフォルト 60000）	いいえ
PGTUNER_LOCK_TIMEOUT_MS	ロックタイムアウト（ミリ秒、デフォルト 5000）	いいえ
PGTUNER_CORS_ALLOW_ORIGINS	カンマ区切りの CORS 許可リスト。* ですべて許可	いいえ
PGTUNER_LINT_DISABLED_RULES	リンターで無効にするルール ID のカンマ区切りリスト	いいえ

接続文字列の形式: postgresql://user:password@host:port/database

最小限のユーザー権限

この MCP サーバーを実行するには、PostgreSQL ユーザーがシステムカタログと拡張機能を照会するための特定の権限を必要とします。以下は、機能セットごとに必要な最小限の権限です。

基本権限 (コア機能に必須)

-- Create a dedicated monitoring user
CREATE USER pgtuner_monitor WITH PASSWORD 'secure_password';

-- Grant connection to the target database
GRANT CONNECT ON DATABASE your_database TO pgtuner_monitor;

-- Grant usage on schemas
GRANT USAGE ON SCHEMA public TO pgtuner_monitor;
GRANT USAGE ON SCHEMA pg_catalog TO pgtuner_monitor;

-- Grant SELECT on user tables and indexes (for table stats and analysis)
GRANT SELECT ON ALL TABLES IN SCHEMA public TO pgtuner_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO pgtuner_monitor;

-- Grant access to system catalog views (read-only)
GRANT pg_read_all_stats TO pgtuner_monitor;  -- PostgreSQL 10+

拡張機能固有の権限

pgstattuple (ブロート検出) の場合:

-- Create the extension (requires superuser or appropriate privileges)
CREATE EXTENSION IF NOT EXISTS pgstattuple;

-- Grant execution on pgstattuple functions
GRANT EXECUTE ON FUNCTION pgstattuple(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstattuple_approx(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstatindex(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstatginindex(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstathashindex(regclass) TO pgtuner_monitor;

-- Alternative: Use pg_stat_scan_tables role (PostgreSQL 14+)
GRANT pg_stat_scan_tables TO pgtuner_monitor;

HypoPG (仮想インデックステスト) の場合:

-- Create the extension (requires superuser or appropriate privileges)
CREATE EXTENSION IF NOT EXISTS hypopg;

-- Grant SELECT on HypoPG views
GRANT SELECT ON hypopg_list_indexes TO pgtuner_monitor;
GRANT SELECT ON hypopg_hidden_indexes TO pgtuner_monitor;

-- Grant execution on HypoPG functions with proper signatures
GRANT EXECUTE ON FUNCTION hypopg_create_index(text) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_drop_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_reset() TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_hide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_unhide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_relation_size(oid) TO pgtuner_monitor;

-- Note: HypoPG operations are session-scoped and don't affect the actual database

完全なセットアップスクリプト

-- 1. Create the monitoring user
CREATE USER pgtuner_monitor WITH PASSWORD 'secure_password';

-- 2. Grant connection and schema access
GRANT CONNECT ON DATABASE your_database TO pgtuner_monitor;
GRANT USAGE ON SCHEMA public TO pgtuner_monitor;

-- 3. Grant read access to user tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO pgtuner_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO pgtuner_monitor;

-- 4. Grant system statistics access
GRANT pg_read_all_stats TO pgtuner_monitor;  -- PostgreSQL 10+

-- Grant access to pg_stat_statements views explicitly
GRANT SELECT ON pg_stat_statements TO pgtuner_monitor;
GRANT SELECT ON pg_stat_statements_info TO pgtuner_monitor;

-- 5. Install and grant access to extensions (as superuser)
-- pg_stat_statements (required)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- pgstattuple (for bloat detection)
CREATE EXTENSION IF NOT EXISTS pgstattuple;
GRANT pg_stat_scan_tables TO pgtuner_monitor;  -- PostgreSQL 14+
-- OR grant individual functions:
-- GRANT EXECUTE ON FUNCTION pgstattuple(regclass) TO pgtuner_monitor;
-- GRANT EXECUTE ON FUNCTION pgstattuple_approx(regclass) TO pgtuner_monitor;
-- GRANT EXECUTE ON FUNCTION pgstatindex(regclass) TO pgtuner_monitor;

-- hypopg (for hypothetical index testing)
CREATE EXTENSION IF NOT EXISTS hypopg;
GRANT SELECT ON hypopg_list_indexes TO pgtuner_monitor;
GRANT SELECT ON hypopg_hidden_indexes TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_create_index(text) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_drop_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_reset() TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_hide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_unhide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_relation_size(oid) TO pgtuner_monitor;

-- 6. Verify permissions
SET ROLE pgtuner_monitor;
SELECT * FROM pg_stat_statements LIMIT 1;
SELECT * FROM pg_stat_activity WHERE pid = pg_backend_pid();
SELECT * FROM pgstattuple('pg_class') LIMIT 1;
SELECT * FROM hypopg_list_indexes();
RESET ROLE;

特定のユーザーを監視から除外する

特定の PostgreSQL ユーザーをクエリ分析および監視結果から除外できます。これは以下のようなものをフィルタリングするのに便利です:

• 監視またはレプリケーションのユーザー
• システムアカウント
• 内部アプリケーションのサービスアカウント

PGTUNER_EXCLUDE_USERIDS 環境変数に、ユーザー OID のカンマ区切りリストを設定します:

# Exclude user IDs 16384, 16385, and 16386
export PGTUNER_EXCLUDE_USERIDS="16384,16385,16386"

特定の PostgreSQL ユーザーの OID を確認するには:

SELECT usesysid, usename FROM pg_user WHERE usename = 'monitoring_user';

設定すると、以下のクエリがフィルタリングされます:

• pg_stat_activity クエリ (usesysid カラムでフィルタリング)
• pg_stat_statements クエリ (userid カラムでフィルタリング)

これは get_slow_queries、get_active_queries、analyze_wait_events、check_database_health、get_index_recommendations などのツールに影響します。

MCP クライアントの設定

cline_mcp_settings.json または Claude Desktop の設定に追加します:

{
  "mcpServers": {
    "pgtuner_mcp": {
      "command": "python",
      "args": ["-m", "pgtuner_mcp"],
      "env": {
        "DATABASE_URI": "postgresql://user:password@localhost:5432/mydb"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

または Streamable HTTP モード

{
  "mcpServers": {
    "pgtuner_mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

セキュリティ強化

pgtuner_mcp の HTTP モード (sse、streamable-http) には認証が含まれていません。これらはローカル専用での使用であれば安全です。ネットワーク経由でデプロイする場合は、認証と TLS を処理するリバースプロキシを必ず前面に配置する必要があります。

接続レベルのセーフガード (組み込み)

プールによって開始されるすべての接続は、ハンドシェイク時に libpq の options を介してセッションレベルのガードを受け取ります:

環境変数	デフォルト	効果
PGTUNER_STATEMENT_TIMEOUT_MS	30000	ステートメントごとの上限。analyze_query の EXPLAIN ANALYZE に上限を適用します。無効にするには 0 を設定します。
PGTUNER_IDLE_TXN_TIMEOUT_MS	60000	孤立したトランザクションを終了させます。無効にするには 0 を設定します。
PGTUNER_LOCK_TIMEOUT_MS	5000	チューニングユーザーのアプリケーションロック待機に上限を適用します。

念には念を — 監視ロールにも設定してください:

ALTER ROLE pgtuner_monitor SET statement_timeout = '30s';
ALTER ROLE pgtuner_monitor SET idle_in_transaction_session_timeout = '60s';

CORS

環境変数	デフォルト	効果
PGTUNER_CORS_ALLOW_ORIGINS	(デフォルト: 任意の localhost/127.0.0.1 ポート、http または https)	カンマ区切りの許可リスト。これを設定すると localhost の正規表現デフォルトが無効になり、リテラルオリジンのマッチングが使用されます。すべてを許可するには * を使用します (allow_credentials=false が強制されます)。

推奨リバースプロキシテンプレート (Caddy)

mcp.example.com {
  basicauth {
    teamuser <hashed_password>
  }
  reverse_proxy localhost:8080
}

含まれていないもの

• Bearer トークン / API キー認証なし (運用者の責務 — リバースプロキシを参照)
• レート制限なし (運用者の責務)
• プロセス内 TLS なし (リバースプロキシを使用してください)
• クライアントごとのツール許可リストなし

サーバーモード

1. 標準 MCP モード (デフォルト)

# Default mode (stdio)
python -m pgtuner_mcp

# Explicitly specify stdio mode
python -m pgtuner_mcp --mode stdio

2. HTTP SSE モード (レガシー Web アプリケーション)

SSE (Server-Sent Events) モードは、MCP 通信のための Web ベースのトランスポートを提供します。HTTP ベースの通信を必要とする Web アプリケーションやクライアントに便利です。

# Start SSE server on default host/port (0.0.0.0:8080)
python -m pgtuner_mcp --mode sse

# Specify custom host and port
python -m pgtuner_mcp --mode sse --host localhost --port 3000

# Enable debug mode
python -m pgtuner_mcp --mode sse --debug

SSE エンドポイント:

エンドポイント	メソッド	説明
/sse	GET	SSE 接続エンドポイント - クライアントはここに接続してサーバーイベントを受信します
/messages	POST	サーバーにメッセージ/リクエストを送信します

SSE 用の MCP クライアント設定:

SSE トランスポートをサポートする MCP クライアント (Claude Desktop やカスタムクライアントなど) の場合:

{
  "mcpServers": {
    "pgtuner_mcp": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

3. Streamable HTTP モード（モダンな MCP プロトコル - 推奨）

streamable-http モードは、単一の /mcp エンドポイントを備えたモダンな MCP Streamable HTTP プロトコルを実装しています。ステートフル（セッションベース）とステートレスの両方のモードをサポートします。

# Start Streamable HTTP server in stateful mode (default)
python -m pgtuner_mcp --mode streamable-http

# Start in stateless mode (fresh transport per request)
python -m pgtuner_mcp --mode streamable-http --stateless

# Specify custom host and port
python -m pgtuner_mcp --mode streamable-http --host localhost --port 8080

# Enable debug mode
python -m pgtuner_mcp --mode streamable-http --debug

ステートフル vs ステートレス:

• ステートフル（デフォルト）: mcp-session-id ヘッダーを使用してリクエスト間でセッション状態を維持します。長時間実行される対話に最適です。
• ステートレス: セッション追跡を行わず、リクエストごとに新しいトランスポートを作成します。サーバーレスデプロイやシンプルなリクエスト/レスポンスパターンに最適です。

エンドポイント: http://{host}:{port}/mcp

利用可能なツール

Note: すべてのツールはユーザー/アプリケーションのテーブルとインデックスのみに焦点を当てています。システムカタログテーブル（pg_catalog、information_schema、pg_toast）はすべての分析から自動的に除外されます。

パフォーマンス分析ツール

ツール	説明
get_slow_queries	pg_stat_statements から詳細な統計情報（合計時間、平均時間、呼び出し回数、キャッシュヒット率）とともにスロークエリを取得します。システムカタログのクエリは除外されます。
analyze_query	EXPLAIN ANALYZE を使用してクエリの実行計画を分析します。自動的な問題検出も含まれます
get_table_stats	サイズ、行数、デッドタプル、アクセスパターンを含む詳細なテーブル統計情報を取得します
analyze_disk_io_patterns	ディスク I/O の読み取り/書き込みパターンを分析し、ホットテーブル、バッファキャッシュ効率、I/O ボトルネックを特定します。分析タイプ（all、buffer_pool、tables、indexes、temp_files、checkpoints）によるフィルタリングをサポートします。

インデックスチューニングツール

ツール	説明
get_index_recommendations	クエリワークロード分析に基づく AI を活用したインデックス推奨
explain_with_indexes	実際のインデックスを作成せずに、仮想インデックスを使用して EXPLAIN を実行し、改善効果をテストします
manage_hypothetical_indexes	HypoPG の仮想インデックスの作成、一覧表示、削除、リセットを行います。既存のインデックスの hide/unhide もサポートします。
find_unused_indexes	安全に削除できる未使用および重複したインデックスを検出します

データベースヘルスツール

ツール	説明
check_database_health	スコアリングを伴う包括的なヘルスチェック（接続、キャッシュ、ロック、レプリケーション、ラップアラウンド、ディスク、チェックポイント）
get_active_queries	アクティブなクエリを監視し、長時間実行トランザクションやブロックされたクエリを検出します。デフォルトではシステムプロセスを除外します。
analyze_wait_events	待機イベントを分析して、I/O、ロック、CPU のボトルネックを特定します。クライアントバックエンドプロセスに焦点を当てます。
review_settings	カテゴリ別に PostgreSQL の設定を確認し、最適化の推奨事項を提示します

ブロート検出ツール（pgstattuple）

ツール	説明
analyze_table_bloat	pgstattuple 拡張機能を使用してテーブルブロートを分析します。デッドタプル数、空き領域、浪費領域の割合を表示します。
analyze_index_bloat	pgstatindex を使用して B-tree インデックスのブロートを分析します。リーフ密度、断片化、空/削除済みページを表示します。GIN および Hash インデックスもサポートします。
get_bloat_summary	最もブロートしたテーブル/インデックス、合計回収可能領域、優先メンテナンスアクションを含む、データベースブロートの包括的な概要を取得します。

Vacuum 監視ツール

ツール	説明
monitor_vacuum_progress	手動 VACUUM、VACUUM FULL、autovacuum 操作を追跡します。進捗率、回収されたデッドタプル、インデックス vacuum のラウンド数、残り時間の推定値を監視します。autovacuum 設定のレビューとメンテナンスが必要なテーブルも含まれます。

ツールパラメータ

get_slow_queries

• limit: 返すクエリの最大数（デフォルト: 10）
• min_calls: 最小呼び出し回数フィルター（デフォルト: 1）
• min_mean_time_ms: 最小平均実行時間（ミリ秒）フィルター
• order_by: mean_time、calls、または rows でソート

analyze_query

• query (必須): 分析する SQL クエリ
• analyze: EXPLAIN ANALYZE を使用してクエリを実行します (デフォルト: true)
• buffers: バッファ統計を含めます (デフォルト: true)
• format: 出力形式 - json、text、yaml、xml

get_index_recommendations

• workload_queries: 分析する特定のクエリのオプションリスト
• max_recommendations: 推奨の最大数 (デフォルト: 10)
• min_improvement_percent: 改善率の最小しきい値 (デフォルト: 10%)
• include_hypothetical_testing: HypoPG でテストします (デフォルト: true)
• target_tables: 特定のテーブルに焦点を当てます

check_database_health

• include_recommendations: 実行可能な推奨事項を含めます (デフォルト: true)
• verbose: 詳細な統計を含めます (デフォルト: false)

analyze_table_bloat

• table_name: 分析する特定のテーブルの名前 (オプション)
• schema_name: スキーマ名 (デフォルト: public)
• use_approx: 大きなテーブルでより高速に分析するために pgstattuple_approx を使用します (デフォルト: false)
• min_table_size_gb: スキーマ全体のスキャンに含める最小テーブルサイズ (GB) (デフォルト: 5)
• include_toast: TOAST テーブルの分析を含めます (デフォルト: false)

analyze_index_bloat

• index_name: 分析する特定のインデックスの名前 (オプション)
• table_name: このテーブル上のすべてのインデックスを分析します (オプション)
• schema_name: スキーマ名 (デフォルト: public)
• min_index_size_gb: 含める最小インデックスサイズ (GB) (デフォルト: 5)
• min_bloat_percent: この割合を超える膨張があるインデックスのみを表示します (デフォルト: 20)

get_bloat_summary

• schema_name: 分析するスキーマ (デフォルト: public)
• top_n: 表示する膨張したオブジェクトの上位件数 (デフォルト: 10)
• min_size_gb: 含める最小オブジェクトサイズ (GB) (デフォルト: 5)

monitor_vacuum_progress

• action: 実行するアクション - progress (実行中の vacuum 操作を監視)、needs_vacuum (vacuum が必要なテーブルを検索)、autovacuum_status (autovacuum 設定を確認)、または recent_activity (最近の vacuum 履歴を表示)
• schema_name: 分析するスキーマ (デフォルト: public、needs_vacuum アクションで使用)
• top_n: 返す結果の件数 (デフォルト: 20)

analyze_disk_io_patterns

• analysis_type: I/O 分析の種類 - all (包括的)、buffer_pool (キャッシュヒット率)、tables (テーブル I/O パターン)、indexes (インデックス I/O パターン)、temp_files (一時ファイルの使用状況)、または checkpoints (チェックポイント I/O 統計)
• schema_name: 分析するスキーマ (デフォルト: public)
• top_n: 表示する I/O 負荷の高いオブジェクトの上位件数 (デフォルト: 20)
• min_size_gb: 含める最小オブジェクトサイズ (GB) (デフォルト: 1)

MCP プロンプト

このサーバーには、ガイド付きチューニングセッション用の事前定義されたプロンプトテンプレートが含まれています:

プロンプト	説明
diagnose_slow_queries	体系的なスロークエリ調査ワークフロー
index_optimization	包括的なインデックス分析とクリーンアップ
health_check	データベース全体のヘルス評価
query_tuning	特定の SQL クエリを最適化
performance_baseline	比較用のベースラインレポートを生成

MCP リソース

静的リソース

• pgtuner://docs/tools - 完全なツールドキュメント
• pgtuner://docs/workflows - 一般的なチューニングワークフローガイド
• pgtuner://docs/prompts - プロンプトテンプレートのドキュメント

動的リソーステンプレート

• pgtuner://table/{schema}/{table_name}/stats - テーブル統計
• pgtuner://table/{schema}/{table_name}/indexes - テーブルインデックス情報
• pgtuner://query/{query_hash}/stats - クエリパフォーマンス統計
• pgtuner://settings/{category} - PostgreSQL 設定 (memory、checkpoint、wal、autovacuum、connections、all)
• pgtuner://health/{check_type} - ヘルスチェック (connections、cache、locks、replication、bloat、all)

PostgreSQL 拡張機能のセットアップ

HypoPG 拡張

HypoPG を使用すると、インデックスを実際に作成せずにテストできます。これは次のような場合に非常に便利です:

• 提案されたインデックスがクエリプランナーに使用されるかどうかをテストする
• 異なるインデックス戦略で実行プランを比較する
• 実際に適用する前にストレージ要件を見積もる

データベースで HypoPG を有効化

HypoPG を使用すると、仮想インデックスをディスク上に作成せずにテストできます。

-- Create the extension
CREATE EXTENSION IF NOT EXISTS hypopg;

-- Verify installation
SELECT * FROM hypopg_list_indexes();

pg_stat_statements 拡張

pg_stat_statements 拡張は、クエリパフォーマンス分析のために必須です。サーバーで実行されるすべての SQL 文のプランニング統計と実行統計を追跡します。

ステップ 1: postgresql.conf で拡張を有効化

postgresql.conf ファイルに次の内容を追加します:

# Required: Load pg_stat_statements module
shared_preload_libraries = 'pg_stat_statements'

# Required: Enable query identifier computation
compute_query_id = on

# Maximum number of statements tracked (default: 5000)
pg_stat_statements.max = 10000

# Track all statements including nested ones (default: top)
# Options: top, all, none
pg_stat_statements.track = top

# Track utility commands like CREATE, ALTER, DROP (default: on)
pg_stat_statements.track_utility = on

Note: shared_preload_libraries を変更した後は、PostgreSQL サーバーの再起動が必要です。

ステップ 2: データベースで拡張を作成

-- Connect to your database and create the extension
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Verify installation
SELECT * FROM pg_stat_statements LIMIT 1;

pgstattuple 拡張

pgstattuple 拡張は、ブロート検出ツール（analyze_table_bloat、analyze_index_bloat、get_bloat_summary）のために必須です。テーブルとインデックスのタプルレベルの統計を取得する関数を提供します。

-- Create the extension
CREATE EXTENSION IF NOT EXISTS pgstattuple;

-- Verify installation
SELECT * FROM pgstattuple('pg_class') LIMIT 1;

パフォーマンスへの影響に関する考慮事項

設定	オーバーヘッド	推奨事項
pg_stat_statements	低 (~1-2%)	常に有効化
track_io_timing	低〜中 (~2-5%)	本番環境で有効化、まずテストする
track_functions = all	低	関数を多用するワークロードで有効化
pg_stat_statements.track_planning	中	プランニングの問題を調査する場合にのみ有効化
log_min_duration_statement	低	スロークエリの特定に推奨

Tip: track_io_timing を有効化する前に、pg_test_timing を使用して特定のシステムでのタイミングのオーバーヘッドを測定してください。

使用例

スロークエリの検索と分析

# Get top 10 slowest queries
slow_queries = await get_slow_queries(limit=10, order_by="total_time")

# Analyze a specific query's execution plan
analysis = await analyze_query(
    query="SELECT * FROM orders WHERE user_id = 123",
    analyze=True,
    buffers=True
)

インデックスの推奨を取得

# Analyze workload and get recommendations
recommendations = await get_index_recommendations(
    max_recommendations=5,
    min_improvement_percent=20,
    include_hypothetical_testing=True
)

# Recommendations include CREATE INDEX statements
for rec in recommendations["recommendations"]:
    print(rec["create_statement"])

データベースのヘルスチェック

# Run comprehensive health check
health = await check_database_health(
    include_recommendations=True,
    verbose=True
)

print(f"Health Score: {health['overall_score']}/100")
print(f"Status: {health['status']}")

# Review specific areas
for issue in health["issues"]:
    print(f"{issue}")

未使用のインデックスを検索

# Find indexes that can be dropped
unused = await find_unused_indexes(
    schema_name="public",
    include_duplicates=True
)

# Get DROP statements
for stmt in unused["recommendations"]:
    print(stmt)

Docker

docker pull  dog830228/pgtuner_mcp

# Streamable HTTP mode (recommended for web applications)
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode streamable-http

# Streamable HTTP stateless mode (for serverless)
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode streamable-http --stateless

# SSE mode (legacy web applications)
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode sse

# stdio mode (for MCP clients like Claude Desktop)
docker run -i \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode stdio

要件

• Python: 3.10+
• PostgreSQL: 12+（推奨: 14+）
• 拡張:
  • pg_stat_statements（クエリ分析に必須）
  • hypopg（オプション、仮想インデックスのテスト用）

依存関係

コア依存関係:

• mcp[cli]>=1.12.0 - Model Context Protocol SDK
• psycopg[binary,pool]>=3.1.0 - 接続プーリングを備えた PostgreSQL アダプター
• pglast>=7.10 - PostgreSQL クエリパーサー

オプション（HTTP モード用）:

• starlette>=0.27.0 - ASGI フレームワーク
• uvicorn>=0.23.0 - ASGI サーバー

統合テスト

統合テストは、Docker 経由で稼働中の PostgreSQL に対してすべての MCP ツールを実行します。

クイックスタート

make up PG=16            # start PG16 container
make test-integration    # run integration suite (defaults to PG=16)
make down                # tear down

対応する PG バージョン: 14、15、16、17（例: make up PG=17）。

CI は .github/workflows/integration.yml を通じて、すべての PR で 4 つの PG バージョンすべてに対してスイートを実行します。

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。