DB Connect MCP

db-connect-mcp - マルチデータベース MCP サーバー

複数のデータベースシステムにまたがる探索的データ分析向けの、読み取り専用 MCP（Model Context Protocol）サーバーです。このサーバーは、PostgreSQL、MySQL、ClickHouse データベースへの安全な読み取り専用アクセスと、包括的な分析機能を提供します。

デモ

クイックスタート

1. インストール：

   pip install db-connect-mcp
   

2. Claude Desktop に追加 claude_desktop_config.json：

   {
     "mcpServers": {
       "db-connect": {
         "command": "python",
         "args": ["-m", "db_connect_mcp"],
         "env": {
           "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
         }
       }
     }
   }
   

3. Claude Desktop を再起動して、データベースへのクエリを開始しましょう！

注：python -m db_connect_mcpを使用すると、Python の Scripts ディレクトリが PATH に含まれていない場合でもコマンドが動作します。既存のmcpServers設定は引き続き有効で、stdio が引き続きデフォルトです。オプションのリモート Streamable HTTP モードでは、データベースや SSH の設定を変更せずに、従来の initialize ベースのクライアントと、2026-07-28 のセッションレス MCP クライアントの両方に/mcpで対応します。既存の HTTP デプロイでは、転送される Host/Origin 値を確認してください：今回のアップグレードによりトランスポートの検証が有効になり、MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINSが必要になる場合があります。

機能

🗄️ マルチデータベース対応

• PostgreSQL - 高度なメタデータと統計情報を含む完全なサポート
• MySQL - MySQL および MariaDB データベースを完全にサポート
• ClickHouse - 分析ワークロードと列指向ストレージに対応

🔍 データベースの探索

• スキーマの一覧表示 - データベース内のすべてのスキーマを表示
• テーブルの一覧表示 - メタデータ（サイズ、行数、コメント）とともにすべてのテーブルを表示
• テーブルの詳細表示 - 列の詳細情報、インデックス、制約を取得
• リレーションシップの表示 - テーブル間の外部キーの関係を確認

📊 データ分析

• 列のプロファイリング - 列データの統計分析
  • 基本統計量（件数、一意な値、NULL 値）
  • 数値統計量（平均値、中央値、標準偏差、四分位数）
  • 値の出現頻度分布
  • カーディナリティ分析
• データのサンプリング - 設定可能な上限でテーブルデータをプレビュー
• カスタムクエリ - 読み取り専用の SQL クエリを安全に実行
• オブジェクト検索 - カタログ全体を読み込まずに、スキーマ、テーブル、ビュー、列、インデックスを検索
• クエリプラン - 推定プランを調べるか、対応している場合はEXPLAIN ANALYZEを明示的に有効化
• 仮想インデックス（PostgreSQL、オプトイン） - 実際のインデックスを作成せずに、HypoPG のプランナー推定値を比較します。管理者がインストールした HypoPG 拡張機能、サーバーでのDB_HYPOPG_ENABLED=true、および各compare_hypothetical_index呼び出しでのopt_in=trueが必要です。単一の単純な SELECT、スキーマ、テーブル、1～4 個の列名を指定してください。コメント、CTE、関数、リテラル、パラメーター、複数のステートメントは拒否されます。このツールは読み取り専用接続を 1 つ使用し、ANALYZEを使わないEXPLAINを実行して、プランニングの待機時間を 5 秒、ロックの待機時間を 1 秒に制限し、セッション内の変更をロールバックします。応答では、結果のプランに含まれる HypoPG インデックス名を照合してhypothetical_index_usedを報告します。候補が使用されなかった場合、無関係であるか、単にプランナーに選択されなかった可能性があります。候補にはスキーマへのUSAGE権限とテーブルへのSELECT権限が必要です。これらの推定値は、実測された速度向上ではありません。

🔒 安全機能

• 読み取り専用の強制 - すべての接続は複数のレベルで読み取り専用になります
• クエリの検証 - SELECT クエリと WITH クエリのみが許可されます
• 自動制限 - 大量の結果セットを防ぐため、クエリに自動で制限が適用されます
• 接続文字列の安全性 - 読み取り専用パラメーターが自動的に追加されます
• データベース固有の安全対策 - 各アダプターで適切な安全対策を実装しています

🔭 可観測性

db-connect-mcp は、MCP SDK に組み込まれている OpenTelemetry サーバー インストルメンテーションを継承します。起動プロセスで SDK とエクスポーターを設定するまで、API は何も実行しません。本番環境で使用する前に、エクスポーターのサンプリングと秘匿化の設定を確認してください。データベース識別子やエラーの詳細には、機密情報が含まれる場合があります。

💡 ベストプラクティス

ヒント： db-connect-mcp は、テーブルとカラムに適切なコメントが付けられたデータベースで最も効果を発揮します。データベースに説明的なコメントが含まれていると、MCP サーバーは AI アシスタントにより豊富なコンテキストを提供できるため、データモデルへの理解が深まり、より正確なクエリ候補を提示できます。

PostgreSQL でのコメントの追加：

COMMENT ON TABLE users IS 'Registered user accounts with profile information';
COMMENT ON COLUMN users.email IS 'Primary email address, used for authentication';
COMMENT ON COLUMN users.is_verified IS 'Whether email has been verified via confirmation link';

MySQL でのコメントの追加：

ALTER TABLE users COMMENT = 'Registered user accounts with profile information';
ALTER TABLE users MODIFY COLUMN email VARCHAR(255) COMMENT 'Primary email address, used for authentication';

サーバーはテーブルの説明時にこれらのコメントを自動的に取得して表示し、AI アシスタントがデータの目的や意味を理解できるようにします。

🔐 SSH トンネルのサポート

• 安全なリモートアクセス - SSH トンネルを介してファイアウォールの内側にあるデータベースに接続できます
• トンネル管理の自動化 - トンネルのライフサイクル（開始、ヘルスチェック、再起動、クリーンアップ）を透過的に管理します
• 信頼性の高いネイティブ転送 - ターゲットの事前チェックと安定したポートの復旧に対応した Paramiko SSHClient トランスポートを使用します
• 柔軟な認証 - パスワードまたは秘密鍵による SSH 認証に対応します
• あらゆるデータベースタイプに対応 - 同じトンネルを通じて PostgreSQL、MySQL、ClickHouse に接続できます

設定の詳細は、SSH トンネルガイドを参照してください。

インストール

前提条件

• Python 3.10 以降
• データベース：PostgreSQL（9.6 以降）、MySQL/MariaDB（5.7/10.2 以降）、または ClickHouse

pip でインストール

pip install db-connect-mcp

これで完了です。パッケージを使用する準備が整いました。

開発者向け：開発環境のセットアップについては、開発ガイドを参照してください。

設定

データベース接続文字列を記述した .env ファイルを作成します。

DATABASE_URL=your_database_connection_string_here

サーバーはデータベースの種類を自動的に検出し、適切な読み取り専用パラメーターを追加します。

PostgreSQL では、ENABLE_PG_STAT_STATEMENTS=true を設定すると、オプションの get_top_queries ツールが利用可能になります。このツールは、データベース管理者が pg_stat_statements をインストールして事前ロードしている場合に、現在のユーザーとデータベースの累積統計を、上限付きで読み取ります。拡張機能のインストールは行いません。明示的に要求されない限りクエリテキストは含まれませんが、機密情報が含まれる場合があります。上限とステータスについては、 上位クエリレポートの仕様を参照してください。

接続文字列の例

サーバーでは、より柔軟で安全な URL 処理が可能になりました。

• ドライバーの自動検出：指定されていない場合、非同期ドライバーが自動的に追加されます
• JDBC URL のサポート：JDBC プレフィックスは自動的に処理されます
  • jdbc:postgresql://... → postgresql+asyncpg://...
  • jdbc:mysql://... → mysql+aiomysql://...
  • すべての方言のバリエーションで動作します（例：jdbc:postgres://、jdbc:mariadb://）
• データベース方言のバリエーション：一般的なバリエーションは自動的に標準化されます
  • PostgreSQL：postgresql、postgres、pg、psql、pgsql
  • MySQL/MariaDB：mysql、mariadb、maria
  • ClickHouse：clickhouse、ch、click
• 許可リストに基づくパラメーターのフィルタリング：安全性が確認されたパラメーターのみが保持されます
• データベース固有のパラメーター：データベースの種類ごとに、サポートされるパラメーターのセットがあります
• 堅牢な解析：さまざまな URL 形式を適切に処理します

PostgreSQL：

# Simple URL (driver automatically added)
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# Common variations (all normalized to postgresql+asyncpg)
DATABASE_URL=postgres://user:pass@host:5432/db  # Heroku, AWS RDS style
DATABASE_URL=pg://user:pass@host:5432/db         # Short form
DATABASE_URL=psql://user:pass@host:5432/db       # CLI style

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:postgresql://user:pass@host:5432/db  # From Java apps
DATABASE_URL=jdbc:postgres://user:pass@host:5432/db    # JDBC with variant

# With explicit async driver
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db

# With supported parameters (see list below)
DATABASE_URL=postgres://user:pass@host:5432/db?application_name=myapp&connect_timeout=10

サポートされている PostgreSQL パラメーター：

• application_name - pg_stat_activity でアプリを識別します（監視に便利です）
• connect_timeout - 接続タイムアウト（秒）
• command_timeout - 操作のデフォルトタイムアウト
• ssl / sslmode - SSL 接続要件（asyncpg との互換性のため自動変換されます）
• server_settings - サーバー設定の辞書
• options - サーバーに送信するコマンドラインオプション
• パフォーマンス調整：prepared_statement_cache_size、max_cached_statement_lifetime など

MySQL/MariaDB：

# Simple URL (driver automatically added)
DATABASE_URL=mysql://root:password@localhost:3306/mydb

# MariaDB URLs (normalized to mysql+aiomysql)
DATABASE_URL=mariadb://user:pass@host:3306/db    # MariaDB style
DATABASE_URL=maria://user:pass@host:3306/db      # Short form

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:mysql://user:pass@host:3306/db     # From Java apps
DATABASE_URL=jdbc:mariadb://user:pass@host:3306/db   # JDBC MariaDB

# With explicit async driver
DATABASE_URL=mysql+aiomysql://user:pass@host:3306/db

# With charset (critical for proper Unicode support)
DATABASE_URL=mariadb://user:[email protected]:3306/db?charset=utf8mb4

サポートされている MySQL パラメーター：

• charset - 文字エンコーディング（例：utf8mb4）- データの整合性に不可欠です
• use_unicode - Unicode サポートを有効にします
• connect_timeout、read_timeout、write_timeout - 各種タイムアウト
• autocommit - トランザクションの自動コミットモード
• init_command - 実行する初期 SQL コマンド
• sql_mode - SQL モード設定
• time_zone - タイムゾーン設定

ClickHouse：

# Simple URL (driver automatically added)
DATABASE_URL=clickhouse://default:@localhost:9000/default

# Short forms (normalized to clickhouse+asynch)
DATABASE_URL=ch://user:pass@host:9000/db         # Short form
DATABASE_URL=click://user:pass@host:9000/db      # Alternative

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:clickhouse://user:pass@host:9000/db  # From Java apps
DATABASE_URL=jdbc:ch://user:pass@host:9000/db         # JDBC with short form

# With explicit async driver
DATABASE_URL=clickhouse+asynch://user:pass@host:9000/db

# With performance settings
DATABASE_URL=ch://user:pass@host:9000/db?timeout=60&max_threads=4

サポートされている ClickHouse パラメーター：

• database - デフォルトのデータベース選択
• timeout、connect_timeout、send_receive_timeout - 各種タイムアウト
• compress、compression - 圧縮を有効にします
• max_block_size、max_threads - パフォーマンス調整

注：

• SSL パラメーター（ssl、sslmode）は、asyncpg に適した形式に自動変換されます
• 証明書ファイルのパラメーター（sslcert、sslkey、sslrootcert）は、互換性の問題を引き起こす可能性があるため除外されます
• 非同期ドライバーで動作することが確認されているパラメーターのみが保持されます

使用方法

サーバーの実行

# Run the server (works everywhere, no PATH configuration needed)
python -m db_connect_mcp

# With environment variable
DATABASE_URL="postgresql://user:pass@host:5432/db" python -m db_connect_mcp

注：python -m db_connect_mcp は、Python の Scripts ディレクトリが PATH に含まれているかどうかにかかわらず動作します。

Claude Code での使用

プロジェクトの .mcp.json に MCP サーバーを追加します。

claude mcp add --transport stdio db-connect --scope project \
  --env DATABASE_URL=postgresql://user:pass@host:5432/db \
  -- python -m db_connect_mcp

または、プロジェクトのルートに .mcp.json を手動で作成します。以下に、サポートされている各データベースの例を示します。

PostgreSQL：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/mydb"
      }
    }
  }
}

MySQL：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@host:3306/mydb"
      }
    }
  }
}

ClickHouse：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "clickhouse+asynch://default:@host:9000/default"
      }
    }
  }
}

SSH トンネル経由の PostgreSQL（データベースがファイアウォールの内側にあり、踏み台ホスト経由でのみアクセスできる場合）：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@db-internal:5432/mydb",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "deployer",
        "SSH_PRIVATE_KEY_PATH": "/home/user/.ssh/id_rsa"
      }
    }
  }
}

SSH トンネル経由の MySQL：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@db-internal:3306/mydb",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "deployer",
        "SSH_PASSWORD": "secret"
      }
    }
  }
}

複数のデータベース（各 MCP サーバーインスタンスは 1 つのデータベースに接続します）：

{
  "mcpServers": {
    "postgres-prod": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@pg-host:5432/prod"
      }
    },
    "mysql-analytics": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@mysql-host:3306/analytics"
      }
    }
  }
}

.mcp.json を作成したら、Claude Code を再起動し、/mcp で確認してください。利用可能なすべてのツールとともに db-connect-mcp が表示されます。

ヒント：SSH_PRIVATE_KEY_PATH の代わりに、SSH_PRIVATE_KEY を使用して秘密鍵の内容を文字列（生の PEM または Base64 エンコードされた PEM）として直接渡すことができます。これは、鍵ファイルのマウントが現実的でない CI/CD やクラウド環境で便利です。

トンネル設定の詳細については、SSH トンネルガイドを参照してください。

Claude Desktop での使用

サーバーを Claude Desktop の設定（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "db-connect": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/db"
      }
    }
  }
}

上記の Claude Code の例で示したデータベース URL の形式と SSH トンネル環境変数は、Claude Desktop でも同様に使用できます。

開発向け：uv を使用してソースから実行する方法については、開発ガイドを参照してください。

データベース機能のサポート

機能	PostgreSQL	MySQL	ClickHouse
スキーマ	✅ 完全	✅ 完全	✅ 完全
テーブル	✅ 完全	✅ 完全	✅ 完全
ビュー	✅ 完全	✅ 完全	✅ 完全
インデックス	✅ 完全	✅ 完全	⚠️ 制限あり
外部キー	✅ 完全	✅ 完全	❌ なし
制約	✅ 完全	✅ 完全	⚠️ 制限あり
テーブルサイズ	✅ 正確	✅ 正確	✅ 正確
行数	✅ 正確	✅ 正確	✅ 正確
カラム統計	✅ 完全	✅ 完全	✅ 完全
サンプリング	✅ 完全	✅ 完全	✅ 完全

MCP リソース

最新の MCP クライアントでは、ツールの呼び出しに加えて、データベースのコンテキストをプライベートでキャッシュ対応の JSON リソースとして検出できます。

• db-connect://database — データベースの識別情報、方言、機能
• db-connect://schema/{schema} — スキーマの数とメタデータ
• db-connect://table/{schema}/{table} — カラム、インデックス、制約、コメント

スキーマとテーブルの形式は、識別子がすでにわかっている場合に直接アクセスできるリソーステンプレートとしても公開されています。

リソースカタログは URI 順に並べられ、100 件ずつカーソルでページ分割されます。カーソルはカタログのスナップショットに紐づいています。ページ間でスキーマまたはテーブルが変更された場合、一貫性のない走査結果を返す代わりに、サーバーはクライアントにページネーションを最初からやり直すよう求めます。

利用可能なツール

すべてのツールは、JSON Schema による入力・出力の仕様、読み取り専用動作のアノテーション、機械可読な構造化結果を公開します。MCP の構造化コンテンツをまだ利用できないクライアント向けに、同じ結果を JSON テキストでも取得できます。構造化されたリスト結果は items エンベロープを使用し、従来のテキスト形式では引き続き JSON 配列を使用します。

get_database_info

方言、バージョン、接続の詳細、読み取り専用ステータス、機能など、データベースのメタデータを取得します。

list_schemas

データベース内のすべてのスキーマを一覧表示します。

list_tables

メタデータとともに、スキーマ内のすべてのテーブルを一覧表示します。

• パラメーター：
  • schema（任意）：スキーマ名（デフォルト：「public」）

describe_table

テーブルの詳細情報を取得します。

• パラメーター：
  • table：テーブル名
  • schema（任意）：スキーマ名（デフォルト：「public」）

analyze_column

統計情報と分布を使用してカラムを分析します。

• パラメーター：
  • table：テーブル名
  • column：カラム名
  • schema（任意）：スキーマ名（デフォルト：「public」）

sample_data

テーブルからデータのサンプルを取得します。

• パラメーター：
  • table：テーブル名
  • schema（任意）：スキーマ名（デフォルト：「public」）
  • limit（任意）：行数（デフォルト：100、最大：1000）

execute_query

読み取り専用の SQL クエリを実行します。

• パラメーター：
  • query：SQL クエリ（SELECT または WITH で始まる必要があります）
  • limit（任意）：最大行数（デフォルト：1000、最大：10000）

get_table_relationships

テーブルの外部キーによるリレーションシップを取得します。

• パラメーター：
  • table：テーブル名
  • schema（任意）：スキーマ名（デフォルト：「public」）

explain_query

データベース固有のクエリ実行計画を取得します。

• パラメーター：
  • query：実行計画を取得する SQL クエリ
  • analyze（任意）：クエリを実行し、実際の実行時統計を含めるかどうか（デフォルト：false）

search_objects

スキーマ、テーブル、ビュー、カラム、インデックスを、詳細度を段階的に変えて検索します。

• パラメーター：
  • pattern：SQL の LIKE パターン。例：%user%
  • object_types（任意）：含めるオブジェクトの種類
  • detail_level（任意）：names、summary、full（デフォルト：summary）
  • schema（任意）：検索対象をスキーマに限定します
  • table（任意）：カラムとインデックスの検索対象をテーブルに限定します
  • limit（任意）：一致する項目の最大数（デフォルト：100、最大：1000）

使用例

設定が完了すると、互換性のある MCP クライアントでサーバーを使用できます。

"Can you analyze my database and tell me about the table structure?"

"Show me the relationships between tables in the public schema"

"What's the distribution of values in the users.created_at column?"

"Give me a sample of data from the orders table"

"Run this query: SELECT COUNT(*) FROM users WHERE created_at > '2024-01-01'"

データベース別の使用例

PostgreSQL を使用する場合：

"List all schemas except system ones"
"Show me the foreign key relationships in the sales schema"
"Analyze the performance of indexes on the products table"

MySQL を使用する場合：

"What storage engines are being used in my database?"
"Show me all tables in the information_schema"
"Analyze the customer_orders table structure"

ClickHouse を使用する場合：

"Show me the partitions for the events table"
"What's the compression ratio for the analytics.clicks table?"
"Sample 1000 rows from the metrics table"

安全性とセキュリティ

• 読み取り専用の意図：書き込みステートメントは拒否され、PostgreSQL と MySQL の接続では読み取り専用トランザクションが使用されます。これは SQL サンドボックスではありません。SELECT は、外部またはセッションレベルの影響を伴う関数を呼び出す場合があります。MySQL の読み取り専用セッションはリクエスト間でプールされません。また、直接の名前付きロック呼び出しと変数への代入は execute_query で拒否されます。特に、SELECT で外部テーブル関数を呼び出す場合がある ClickHouse では、すべてのエンジンで最小権限のデータベースロールを使用してください。
• クエリの制限：execute_query は、返される行数とシリアル化されたレスポンスのサイズを制限しますが、データベースでの処理全体やプロセスメモリのピーク使用量は制限しません。ClickHouse の同期ドライバーは、アプリケーションが確認する前に結果全体をバッファーする場合があります。データベース側で実行、メモリ、アクセスの制限を設定してください。ヘルスチェックとクエリの安全性に関する注意事項を参照してください。

開発

詳細な開発環境のセットアップ、テスト、貢献のガイドラインについては、開発ガイドを参照してください。

プロジェクト構成

db-connect-mcp/
├── src/
│   └── db_connect_mcp/
│       ├── adapters/         # Database-specific adapters
│       │   ├── __init__.py
│       │   ├── base.py      # Base adapter interface
│       │   ├── postgresql.py # PostgreSQL adapter
│       │   ├── mysql.py     # MySQL adapter
│       │   └── clickhouse.py # ClickHouse adapter
│       ├── core/            # Core functionality
│       │   ├── __init__.py
│       │   ├── connection.py # Database connection management
│       │   ├── executor.py  # Query execution
│       │   ├── inspector.py # Metadata inspection
│       │   ├── analyzer.py  # Statistical analysis
│       │   └── tunnel.py   # SSH tunnel management
│       ├── models/          # Data models
│       │   ├── __init__.py
│       │   ├── capabilities.py # Database capabilities
│       │   ├── config.py    # Configuration models
│       │   ├── database.py  # Database models
│       │   ├── query.py     # Query models
│       │   ├── statistics.py # Statistics models
│       │   └── table.py     # Table metadata models
│       ├── __init__.py
│       ├── __main__.py      # Module entry point
│       └── server.py        # Main MCP server implementation
├── tests/
│   ├── unit/            # Unit tests (mocked)
│   ├── module/          # Module tests (single component + DB)
│   ├── integration/     # Integration tests (full stack)
│   └── conftest.py      # Shared fixtures
├── .env.example         # Example environment configuration
├── pyproject.toml      # Project dependencies and console scripts
└── README.md          # This file

アーキテクチャ

このサーバーでは、複数のデータベースシステムをサポートするためにアダプターパターンを使用しています。

• アダプター：各データベースの種類に、それぞれのデータベース固有の機能を実装するアダプターがあります
• コア：接続管理、クエリ実行、メタデータの検査に関する共通機能
• モデル：型安全性と検証のための Pydantic モデル
• サーバー：リクエストを適切なコンポーネントにルーティングする MCP サーバーの実装

テストの実行

# Start local test database (PostgreSQL 17 with sample data)
cd tests/docker && docker-compose up -d && cd ../..

# Run all tests in parallel (preferred - 6 workers)
uv run pytest -n 6

# Run specific test modules
uv run pytest tests/module/test_inspector.py -v -n 6
uv run pytest tests/integration/ -v -n 6

# Stop test database
cd tests/docker && docker-compose down && cd ../..

# Reset database (clean slate with fresh data)
cd tests/docker && docker-compose down -v && docker-compose up -d && cd ../..

ローカルテスト用データベース：

• 7 つのテーブルに 5 万件以上のサンプルデータを含む PostgreSQL 17
• Docker Compose によって自動的に初期化されます
• クラウドデータベースや .env の設定は不要です
• 詳細はDocker のセットアップを参照してください

詳しいテスト手順については、開発ガイドとテストガイドを参照してください。

トラブルシューティング

接続の問題

• DATABASE_URL が正しく、適切なドライバーが含まれていることを確認します
• データベースへのネットワーク接続を確認します
• データベースユーザーに適切な読み取り権限があることを確認します
• PostgreSQL の場合：SSL が必要かどうかを確認します（?ssl=require）
• MySQL の場合：文字セットの設定を確認します（?charset=utf8mb4）
• ClickHouse の場合：ポートを確認します（デフォルトはネイティブ接続で 9000、HTTP で 8123）

データベース固有の問題

PostgreSQL：

• 非同期操作では asyncpg ドライバーが指定されていることを確認します
• クラウドデータベースでは SSL 証明書が必要な場合があります

MySQL/MariaDB：

• 非同期サポートには aiomysql ドライバーを使用します
• MySQL のバージョン互換性を確認します（5.7 以降、または MariaDB 10.2 以降）
• 文字セットと照合順序の設定を確認します

ClickHouse：

• 非同期操作では asynch ドライバーを使用します
• ClickHouse では外部キーと制約のサポートが限定的であることに注意してください
• 一部の統計関数は使用できない場合があります

権限エラー

• データベースユーザーには、分析対象のスキーマ／テーブルに対する少なくとも SELECT 権限が必要です
• 一部の統計関数では、追加の権限が必要になる場合があります
• ClickHouse では、システムテーブルに対する特定の権限が必要になる場合があります

大きな結果セット

• limit パラメーターを使用して、結果のサイズを調整します
• メモリの問題を防ぐため、サーバーは結果を自動的に制限します
• 大規模な分析では、より具体的なクエリの使用を検討してください

作成者

ユリ・ギ が作成しました。

貢献

貢献を歓迎します！サーバーはデフォルトで読み取り専用かつ安全に設計されています。新機能を追加する場合は、これらの安全性を維持してください。

ライセンス

MIT ライセンス - 詳細は LICENSE ファイルをご覧ください