postgres

PostgreSQL 読み取り専用クエリスキル

設定済みの PostgreSQL データベースに対して、安全な読み取り専用クエリを実行します。

前提条件

• Python 3.8+
• psycopg2-binary：pip install -r requirements.txt

セットアップ

スキルディレクトリまたは ~/.config/claude/postgres-connections.json に connections.json を作成します。

セキュリティ：認証情報が含まれるため、ファイルのアクセス権を 600 に設定してください。

chmod 600 connections.json

{
  "databases": [
    {
      "name": "production",
      "description": "Main app database - users, orders, transactions",
      "host": "db.example.com",
      "port": 5432,
      "database": "app_prod",
      "user": "readonly_user",
      "password": "your-password",
      "sslmode": "require"
    }
  ]
}

設定フィールド

フィールド	必須	説明
name	はい	データベースの識別子（大文字と小文字を区別しません）
description	はい	このデータベースに含まれるデータの説明（自動選択に使用）
host	はい	データベースのホスト名
port	いいえ	ポート番号（デフォルト：5432）
database	はい	データベース名
user	はい	ユーザー名
password	はい	パスワード
sslmode	いいえ	SSL モード：disable、allow、prefer（デフォルト）、require、verify-ca、verify-full

使い方

設定済みデータベースの一覧表示

python3 scripts/query.py --list

データベースへのクエリ

python3 scripts/query.py --db production --query "SELECT * FROM users LIMIT 10"

テーブルの一覧表示

python3 scripts/query.py --db production --tables

スキーマの表示

python3 scripts/query.py --db production --schema

結果数の制限

python3 scripts/query.py --db production --query "SELECT * FROM orders" --limit 100

データベースの選択

ユーザーの意図をデータベースの description に照らし合わせます。

ユーザーの質問	説明に含まれる語句
ユーザー、アカウント	users、accounts、customers
注文、売上	orders、transactions、sales
分析、メトリクス	analytics、metrics、reports
ログ、イベント	logs、events、audit

判断が難しい場合は、--list を実行し、どのデータベースを使うかユーザーに尋ねてください。

安全機能

• 読み取り専用セッション：接続は PostgreSQL の readonly=True モードを使用します（主要な保護機能）。
• クエリの検証：SELECT、SHOW、EXPLAIN、WITH クエリのみ許可されます。
• 単一ステートメント：クエリごとの複数ステートメントは拒否されます。
• SSL サポート：暗号化接続用の SSL モードを設定できます。
• クエリタイムアウト：30 秒のステートメントタイムアウトが適用されます。
• メモリ保護：メモリ不足を防ぐため、クエリあたりの最大行数は 10,000 行です。
• 列幅の上限：読みやすい出力にするため、各列の幅は最大 100 文字です。
• 認証情報のサニタイズ：エラーメッセージからパスワードが漏えいしません。

トラブルシューティング

エラー	解決方法
設定が見つからない	スキルディレクトリに connections.json を作成します
認証に失敗	設定のユーザー名とパスワードを確認します
接続がタイムアウト	ホストとポートを確認し、ファイアウォール／VPN を確認します
SSL エラー	ローカルデータベースの場合は "sslmode": "disable" を試します
アクセス権の警告	chmod 600 connections.json を実行します

終了コード

• 0：成功
• 1：エラー（設定がない、認証失敗、無効なクエリ、データベースエラー）

ワークフロー

1. --list を実行して、利用可能なデータベースを表示します
2. ユーザーの意図をデータベースの説明に照らし合わせます
3. --tables または --schema を実行して、構造を確認します
4. 適切な LIMIT を指定してクエリを実行します