MCP Database Doctor

MCP Database Doctor

AI エージェントがリリースする前に、危険な PostgreSQL マイグレーションや遅いクエリを検出します — オフラインで、DB 認証情報も不要です。

AI コーディングエージェント向けの、オフライン PostgreSQL マイグレーションの lint とクエリ分析です。本番環境に到達する前に、テーブルロックを引き起こす DDL、危険な型変更、遅いクエリのパターン、実行計画の問題を検出します。データがマシンの外に出ることはなく、データベースへの接続も不要です。

---

クイックインストール

Cursor

上のボタンをクリックすると、ワンステップでインストールできます。または、次のリンクを使用してください：
cursor://anysphere.cursor-deeplink/mcp/install?name=database-doctor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1kYXRhYmFzZS1kb2N0b3IiXX0=

または、~/.cursor/mcp.json に手動で追加します：

{
  "mcpServers": {
    "database-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-database-doctor"]
    }
  }
}

Claude Code

claude mcp add database-doctor -- npx -y mcp-database-doctor

または、Cursor プラグインマーケットプレイスで利用できる場合：

/plugin marketplace add petrovicistefan/mcp-marketplace

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "database-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-database-doctor"]
    }
  }
}

VS Code

または、.vscode/mcp.json に追加します：

{
  "mcpServers": {
    "database-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-database-doctor"]
    }
  }
}

任意の MCP クライアント

npx -y mcp-database-doctor

⭐ このリポジトリにスターを付けて、プロジェクトを支援し、最新情報を受け取りましょう！ → スターを付ける

---

📋 目次

• Database Doctor を選ぶ理由
• ユースケース
• チェック項目
• 比較
• ツール
• プロンプトの例
• 制限事項
• 開発
• 作者が提供するその他の MCP サーバー
• コントリビューション
• ライセンス

---

Database Doctor を選ぶ理由

仕組み： AI エージェントが、一見無害そうなマイグレーションを生成します。たとえば、CREATE INDEX、ALTER COLUMN ... TYPE、ADD COLUMN NOT NULL です。しかし、どれも本番テーブルを数分から数時間ロックし、すべての書き込みをブロックして、アプリを停止させる可能性があります。

Database Doctor は、リリース前にこれらを検出します：

• データベース不要：静的解析のみで、未コミットのコードにも対応します
• 認証情報不要：データベースへの接続も、SQL の実行も行いません
• ネットワーク不要：すべてマシン上でローカルに実行されます
• AI ネイティブ：AI コーディングエージェント（Claude Code、Cursor、GitHub Copilot）向けに設計されています

使用する場面

✅ マイグレーションのリリース前 — CONCURRENTLY を付けていない CREATE INDEX、危険な型変更、揮発性のデフォルト値を検出します
✅ 遅いクエリのレビュー — SELECT *、深い OFFSET、上限のない書き込み、インデックスのない述語を検出します
✅ EXPLAIN プランの分析 — 大規模なシーケンシャルスキャン、行数推定の誤り、ソートのディスクへのスピル、高いループ回数を特定します
✅ インデックスの提案 — WHERE 句のカラムに対する、慎重な DDL 候補を取得します

---

ユースケース

1. AI エージェントによるコードレビュー

エージェントがマイグレーションを作成し、コミット前に Database Doctor がレビューします。

User: "Add an email column to the users table"

Agent writes:
  ALTER TABLE users ADD COLUMN email VARCHAR(255) NOT NULL;

Database Doctor flags:
  ⚠️  NOT_NULL_CHANGE (medium severity)
  Adding NOT NULL requires a full table scan and may hold locks.
  Recommendation: Backfill data first, then add NOT NULL separately.

Agent rewrites:
  ALTER TABLE users ADD COLUMN email VARCHAR(255);
  -- Backfill in application code or batched UPDATE
  ALTER TABLE users ALTER COLUMN email SET NOT NULL;

2. コミット前チェック

危険なマイグレーションを CI に到達する前に検出します。

AI に次のように依頼してください：「db/migrations/ 内のすべてのマイグレーションの安全性をチェックしてください」

Database Doctor は各ファイルをレビューし、次の項目を報告します：

• 破壊的な DDL（DROP、TRUNCATE）
• ブロッキングを伴うインデックス作成
• テーブルの再書き込みを伴うカラム変更
• NOT VALID を指定しない制約の検証
• CONCURRENTLY 操作を実行できないトランザクション

3. クエリの最適化

パフォーマンスの問題を本番環境に到達する前に発見します。

エージェントは次のクエリを生成します：

SELECT * FROM orders 
WHERE LOWER(email) = '[email protected]' 
OFFSET 10000 
LIMIT 20;

Database Doctor は次の項目を検出します：

• SELECT_STAR：ワイルドカード射影はスキーマと呼び出し元を密結合します
• FUNCTION_PREDICATE：LOWER() は email のインデックスを使用できない可能性があります
• DEEP_OFFSET：Offset 10000 は多くの行を破棄するため、キーセットページネーションを使用してください

4. EXPLAIN プランのレビュー

遅いクエリの実行プランを送信して分析します。

# On your test database
EXPLAIN (FORMAT JSON) SELECT ... > plan.json

# In your AI client
"Review this execution plan from plan.json"

Database Doctor は次の項目を検出します：

• 大規模なテーブルに対するシーケンシャルスキャン
• 行数の推定誤差（10 倍以上）
• ディスクにスピルするソート処理
• ネストされた結合での高いループ回数

---

チェック項目

マイグレーションの安全性（check_migration）

チェック	重要度	検出する内容
DESTRUCTIVE_DDL	高	DROP TABLE/SCHEMA/DATABASE、TRUNCATE
COLUMN_TYPE_CHANGE	高	ALTER COLUMN ... TYPE（テーブルの再書き込みと強力なロック）
BLOCKING_INDEX	中	CONCURRENTLY を指定しない CREATE INDEX（書き込みをブロック）
CONCURRENT_INDEX_TRANSACTION	高	BEGIN/COMMIT 内の CONCURRENTLY（無効）
UNIQUE_INDEX_DATA	中	UNIQUE インデックスには互換性のある既存データが必要
NOT_NULL_CHANGE	中	SET NOT NULL または ADD COLUMN NOT NULL（テーブルスキャン）
CONSTRAINT_VALIDATION	中	NOT VALID を指定しない ADD FOREIGN KEY / CHECK
VOLATILE_DEFAULT	高	random()、clock_timestamp()、nextval() を使った DEFAULT
CASCADE	高	CASCADE は依存オブジェクトに影響する可能性があります

クエリ分析（analyze_query）

チェック	重要度	検出する内容
SELECT_STAR	低	ワイルドカード射影は結合度を高めます
UNBOUNDED_WRITE	高	WHERE を指定しない UPDATE/DELETE
DEEP_OFFSET	中	大きな OFFSET は行を破棄するため、キーセットページネーションを使用してください
FUNCTION_PREDICATE	中	WHERE 句内の関数はインデックスを使用できない可能性があります
UNORDERED_LIMIT	低	ORDER BY のない LIMIT は結果が不安定になります
CROSS_JOIN	中	明示的な CROSS JOIN は行数を増大させます
NULL_NOT_IN	中	NULL を含む NOT IN サブクエリは予期しない結果を生む可能性があります
RANDOM_SORT	中	ORDER BY random() はすべての行のソートが必要になる場合があります

EXPLAIN プラン分析（explain_plan）

チェック	重要度	検出する内容
LARGE_SEQ_SCAN	中	推定行数が 10,000 以上のシーケンシャルスキャン
ROW_ESTIMATE_ERROR	中	推定行数と実際の行数の差が 10 倍以上
SORT_SPILL	中	ソートがディスクにスピル（work_mem を増やしてください）
HIGH_LOOPS	中	プランノードが 1000 回以上実行されます

---

比較

2026年10月時点。すべての比較は公開ドキュメントに基づき、慎重に記載しています。

機能	Database Doctor	MigrationPilot	Locksmith	Ballast	DBHub
オフライン分析	✅ DB 接続不要	✅ 任意	✅ DB 接続不要	❌ DB が必要	❌ DB に接続
マイグレーションのリント	✅ 9 個のマイグレーションルール	✅ 112 個のルール	✅ 9 個のルール＋書き換え	✅ Squawk の上位互換	❌ リンターではありません
クエリ分析	✅ 8 個のクエリパターン	❌ マイグレーションのみ	❌ マイグレーションのみ	❌ マイグレーションのみ	✅ 実行による分析
EXPLAIN プラン分析	✅ 4 個のプランチェック	❌	❌	❌	✅ EXPLAIN による分析
インデックスの提案	✅ 保守的な候補	❌	❌	❌	❌
MCP サーバー	✅ 5 個のツール	✅ 4 個のツール	✅ 3 個のツール	⚠️ 不明	✅ マルチ DB ゲートウェイ
認証情報不要	✅ 接続は一切行いません	⚠️ 任意	✅ 接続は一切行いません	❌ DSN が必要	❌ 接続が必要
AI エージェントとの統合	✅ MCP ネイティブ	✅ MCP＋CLI	✅ MCP ネイティブ	⚠️ MCP 対応は不明	✅ マルチ DB MCP
自動修正	❌ 推奨のみ	✅ 20 個の自動修正	✅ そのまま貼り付けられる書き換え	⚠️ 不明	❌
PostgreSQL 専用	✅ PostgreSQL を第一に設計	✅ PostgreSQL 専用	✅ PostgreSQL 専用	✅ PostgreSQL 専用	❌ マルチ DB
ライセンス	MIT	MIT	MIT	MIT	MIT

当ツールの差別化要素：

• 最も幅広い対象範囲：マイグレーション＋クエリ＋EXPLAIN プラン＋インデックスの提案（1 つのツールで 4 つの機能）
• セットアップ不要：データベースも認証情報も設定も不要。コミット前のコードでも動作します
• プライバシーを最優先：完全にオフラインで動作し、データが外部に送信されることはありません
• PostgreSQL ネイティブ：正規表現ベースではなく、コメント、文字列、ドル引用、入れ子のブロックを処理します
• 軽量：MCP SDK と Zod 以外の依存関係はありません

代替ツールを使う場合：

• MigrationPilot：112 個のルール、自動修正、VS Code 拡張機能、SARIF 対応の GitHub Action が必要な場合
• Locksmith：そのまま貼り付けられる安全な書き換えと、ロックマトリックスのドキュメントが必要な場合
• Ballast：実際のテーブルサイズに基づいて重み付けされた、負荷を考慮する分析が必要な場合（DB 接続が必要）
• DBHub：調査やガード付き SQL 実行のために、稼働中のデータベースへの接続が必要な場合

---

ツール

Database Doctor は AI エージェント向けに 5 個の MCP ツールを提供します。

ツール	入力	出力
analyze_query	sql（文字列）	重要度、メッセージ、推奨事項、文番号を含む SQL アンチパターン
check_migration	sql（文字列）	破壊的な DDL、ロックのリスク、トランザクションの競合、制約検証の問題
suggest_indexes	sql（文字列） existingIndexes（任意の配列）	保守的なインデックス DDL 候補（適用されることはなく、EXPLAIN による検証が必要）
explain_plan	plan（JSON 文字列）	大規模スキャン、行数見積もりの誤差、ソートのスピル、高いループ回数
health_report	queries（任意の配列） migrations（任意の配列） plans（任意の配列）	提供された成果物の総合レビュー（稼働中のデータベースの健全性ではありません）

すべてのツールは読み取り専用で、冪等性があり、認証は不要です。

レポートには次の内容が含まれます：

• code：検出事項の種類を示す安定した識別子
• severity：high、medium、low
• message：問題の内容
• recommendation：修正方法
• statement：複数文の SQL における該当文（1 から始まる番号）

---

プロンプトの例

マイグレーションの場合：

"Check this migration for locking issues"
"Review db/migrations/003_add_email_index.sql before I commit"
"Is this ALTER TABLE safe for a production table with 10M rows?"

クエリの場合：

"Analyze this query for performance issues"
"Why is this SELECT slow?"
"Review the queries in src/repositories/user.ts"

EXPLAIN プランの場合：

"Review this EXPLAIN plan from plan.json"
"What's wrong with this execution plan?"

インデックスの提案の場合：

"What indexes would help this query?"
"Suggest indexes for this WHERE clause"

総合レビューの場合：

"Review all migrations in db/migrations/ for safety"
"Check queries.sql and migrations.sql for issues"

開発ワークフローとの統合：

"Before I commit, check the migration I just generated"
"Add this to pre-commit: check all .sql files for dangerous patterns"

---

制限事項

Database Doctor はヒューリスティックな静的分析を使用しており、完全な PostgreSQL パーサーでも、安全性を証明するものでもありません。

適切に処理できるもの

✅ コメント（単一行の -- と入れ子のブロック /* */）
✅ 文字列リテラル（エスケープされた E'...' を含む）
✅ ドル引用文字列（$$、$tag$）
✅ 引用符付き識別子（"column_name"）
✅ 一般的な DDL と DML のパターン

既知の制限事項

⚠️ 完全な SQL パーサーではありません：複雑な CTE、ネストされたスコープ、特殊な DDL では、誤検知や検出漏れが発生する可能性があります
⚠️ スキーマのメタデータはありません：カラムが存在するか、どのような型か、どのようなインデックスがあるかを検証できません
⚠️ インデックスの推定は保守的です：引用符で囲まれていないテーブルを1つだけサポートし、結合やサブクエリ、複合インデックスの最適化には対応していません
⚠️ ストアドプロシージャの本体は解析しません：関数、DO ブロック、動的文字列内の SQL は検査されません
⚠️ 実行はしません：実際のクエリ時間、ロック時間、実際のプランコストは測定できません
⚠️ PostgreSQL を優先しています：MySQL、SQL Server、Oracle、その他の方言ではテストされていません

検出結果の意味

✅ 検出結果あり：適用する前に、該当するパターンを確認してください
⚠️ 検出結果なし：SQL が安全、高速、または有効な PostgreSQL であることを意味するものではありません
⚠️ 検出結果がないことは、本番環境でマイグレーションを実行する許可ではありません

本番環境に適用する前に、必ず安全な環境でマイグレーションをテストしてください。

---

開発

要件： Node.js >=22.18（Node 24 を推奨）

# Install dependencies
npm install

# Type check
npm run check

# Run tests (core logic, no network)
npm test

# Build
npm run build

# Integration tests (MCP stdio after build)
npm run test:integration

# Verify package contents
npm pack --dry-run

テストカバレッジ： 以下を対象とする53件のコアテスト：

• SQL のマスキング（コメント、文字列、ドル引用符、引用符で囲まれた識別子）
• クエリ解析（全8ルール）
• マイグレーションチェック（全9ルール）
• EXPLAIN プランの解析と分析
• インデックス提案ロジック
• ヘルスレポートの集計

CI： GitHub Actions は、すべてのプッシュと PR で型チェック、テスト、ビルド、統合テスト、パッケージ検証を実行します。

---

作者によるその他の MCP サーバー

petrovicistefan MCP suite の一部です。AI コーディングエージェント向けのローカルファーストなガードレールを提供します。

このファミリーのツールはすべて、次の特徴があります：

• ✅ ローカルファースト：すべてがお使いのマシン上で動作します
• ✅ 読み取り専用：破壊的な操作はありません（明示的にオプトインした場合を除く）
• ✅ API キー不要：アカウント、テレメトリー、ネットワーク呼び出しは不要です（オプトインした場合を除く）
• ✅ AI ネイティブ：AI コーディングエージェント専用に構築されています

サーバー	目的
mcp-security-guard	MCP サーバーを監査し、ツールポイズニング、ラグプル、漏洩したシークレットを検出します（OWASP MCP Top 10）
mcp-cost-optimizer	高コストなクラウドのパターンが本番環境に到達する前に検出します
mcp-database-doctor	危険な PostgreSQL のマイグレーションと遅いクエリを検出します（現在のページ）
mcp-dependency-doctor	古い依存関係、CVE、ライセンスの問題を検出します
mcp-seo-auditor	SEO とアクセシビリティの問題についてウェブページを監査します
mcp-api-guardian	ベストプラクティスに照らして REST API の設計を検証します
mcp-marketplace	ファミリー内のすべての MCP サーバーを閲覧、検索できます

---

商用ロードマップ

永久無料：

• ローカルでのクエリ、マイグレーション、EXPLAIN プランの分析
• 5つすべての MCP ツール
• 使用制限なし
• テレメトリーなし

Pro プラン（予定、オプトイン）：

• 履歴の追跡（変更前と変更後の比較）
• CI ポリシーと高度な推奨事項
• ホスト型 HTTP API（MCP 以外の統合向け）
• ホスト型パスのみ、コントロールプレーンによるクォータ管理

Team プラン（予定、オプトイン）：

• 共有マイグレーションポリシー
• レポートの一元管理
• 全環境にわたるクエリ分析

ローカルツールは今後も永久に無料かつオフラインで利用できます。 有料機能は追加機能であり、明示的なオプトインが必要です。

---

貢献

貢献を歓迎します！まずはCONTRIBUTING.mdをお読みください。

初めての貢献におすすめ：

• 誤検出や検出漏れに対するテストケースの追加
• ドキュメントやサンプルの改善
• 対応する PostgreSQL のバージョンの追加
• クエリやマイグレーションのルールの拡張

現在受け付けていないもの：

• 明確なユースケースがない、ほかのデータベース（MySQL、SQL Server など）への対応
• ネットワークを利用する機能（ローカルファーストを維持します）

貢献ガイド · 未解決の課題 · 誤検出を報告

---

ライセンス

MIT © Stefan Petrovici

詳細はLICENSEをご覧ください。

---

作者について

私はStefan Petroviciです。ITに情熱を持ち、夫であり父親でもあります。Database DoctorとMCPスイート全体を一人で開発しました。仕事を探しています。

フロントエンド、バックエンド、API、デプロイまで、ウェブアプリケーションを一貫して開発しています。また、開発が必要なものであれば、ほかの仕事にも喜んで取り組みます。このリポジトリには、テスト、CI、丁寧なドキュメント、細部へのこだわりなど、私の仕事の進め方が表れています。

WordPressやWooCommerceのプラグインも開発しており、pluginsforstores.comで公開しています。

採用中のチームの方は、[email protected]までご連絡ください。

---

⭐ このプロジェクトを応援する

役に立ったと思ったら、このリポジトリにスターを付けてください！

GitHubのスターは、ほかの開発者がこのプロジェクトを見つける助けになり、後で見返すための保存にもなります。オープンソースを応援していただき、ありがとうございます！

---

Database Doctorは、このドキュメントで言及されているPostgreSQL、Anthropic、その他のベンダーとは提携していません。