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	users、accounts、customers
orders、sales	orders、transactions、sales
analytics、metrics	analytics、metrics、reports
logs、events	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 を指定してクエリを実行します