MySQL Audit

mysql_audit_ai_agent

AI コーディングエージェント向けの MySQL スキーマ変更安全性レビューです。

Claude Code、Cursor などのエージェントがマイグレーションを実行する前に、SQL を review_migration に送信すると、判定（safe / review / block）と、各リスクの 行番号、本番環境で起きること、安全な記述方法が返されます。チェックは別の LLM による推測ではなく、DBA の経験に基づく決定論的なルールです。

ステータス：ベータ版。12 個すべてのルールを、CI で実際の MySQL 8.0 および 8.4 に対して検証しています。DBA の皆さんは、試用キットをお試しいただき、誤った結果をご報告ください。

ルール

ID	チェック内容	デフォルト	必要な情報
L01	明示的な ALGORITHM / LOCK がない DDL、ALGORITHM=COPY、LOCK=SHARED/EXCLUSIVE	警告 / ブロック
L02	テーブルコピーを強制するカラム変更：型変更、VARCHAR の縮小または 255 バイトをまたぐ変更、ENUM の並べ替え、文字セット変換、主キーの削除	ブロック	正確な判定にはスキーマが必要
L03	大きなテーブルの行に触れる DDL：gh-ost / pt-online-schema-change を使用	警告	統計情報
L04	短い SET SESSION lock_wait_timeout のない DDL（メタデータロックの滞留）	警告
L05	foreign_key_checks=1 の状態での ADD FOREIGN KEY（COPY のみ）	ブロック
L06	大きなテーブルに対する 1 トランザクション内の UPDATE / DELETE / INSERT ... SELECT（レプリケーション遅延）	警告	統計情報
L07	カラム、テーブル、データベースの DROP / TRUNCATE / RENAME	ブロック
L08	WHERE のない UPDATE / DELETE、ORDER BY のない LIMIT	ブロック / 警告
L09	キー範囲またはバッチサイズで制限されていないバックフィル	警告 / 情報
L10	BIGINT より小さい自動インクリメントカラム、utf8 / utf8mb3	警告
L11	インデックスの先頭カラムではないカラムを使った WHERE / JOIN	警告	スキーマ
L12	f-string、テンプレートリテラル、文字列連結、% / .format / Sprintf による SQL の構築（SQL インジェクション）	ブロック	ソースコード

同じスクリプト内で先に作成されたテーブルは空として扱われるため、それらに対する DDL は警告されません。

• スキーマ：現在の CREATE TABLE 文（SHOW CREATE TABLE）。
• 統計情報：おおよその行数。{"orders": 25000000} のように指定します。取得には SELECT table_name, table_rows FROM information_schema.tables WHERE table_schema = DATABASE() を使用します。 1,000,000 行以上のテーブルは大きいもの、10,000 行未満のテーブルは小さいものとして扱います。

AI エージェントとの使用（MCP）

uv が必要です。サーバーは stdio 経由でローカル実行されるため、SQL がマシンの外部に送信されることはありません。

Claude Code

claude mcp add mysql-audit -- uvx mysql-audit-ai-agent

Cursor、Windsurf、Claude Desktop などの MCP クライアント（mcp.json / claude_desktop_config.json）：

{
  "mcpServers": {
    "mysql-audit": { "command": "uvx", "args": ["mysql-audit-ai-agent"] }
  }
}

Claude Desktop、ワンクリック：mysql-audit.mcpb を最新リリースからダウンロードして開きます。

ツール：review_migration(sql, schema?, stats?)、review_query(sql, schema?, stats?)、 review_code(code)、explain_rule(rule_id)、list_rules()。

エージェント評価では、Claude Code は追加のプロンプトなしで、10 件中 10 件のマイグレーションタスクにおいて自律的にツールを呼び出しました。

コマンドライン

pip install mysql-audit-ai-agent
mysql-audit migrations/20261027_add_index.sql --schema schema.sql
mysql-audit migration.sql --stats rows.json --format json
mysql-audit --code app/models/user.py      # SQL injection check

終了コードは、safe が 0、review が 1、block が 2 です。そのため、CI のゲートとして使用できます。

GitHub Action

各プルリクエストで追加または変更されたマイグレーションをレビューし、差分内の該当行に注釈を付け、プルリクエスト上のサマリーコメントを 1 つに保って最新の状態に更新し、block の場合はチェックを失敗させます。

# .github/workflows/mysql-audit.yml
name: MySQL Audit
on: pull_request
permissions:
  contents: read
  pull-requests: write   # for the summary comment
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jimmyjan0824/[email protected]
        with:
          paths: db/migrate/**/*.sql      # default: **/*.sql
          schema: db/schema.sql           # optional, makes checks exact
          # stats: db/table_rows.json     # optional row counts, enables large-table rules
          # code-paths: app/**/*.py       # optional SQL injection check
          # fail-on: review               # block (default), review or never

開発

pip install -e ".[dev]"
pytest

各ルールには、tests/ に肯定ケースと否定ケースがあります。

tests/test_mysql_oracle.py は実際のサーバーに対してルールを検証します。各 ALTER は ALGORITHM=INPLACE, LOCK=NONE を指定して実行され、MySQL が拒否するかどうかが ルールの判定と一致する必要があります。CI では MySQL 8.0 および 8.4 で実行します。ローカルでは次のように実行します。

docker run -d -e MYSQL_ROOT_PASSWORD=root -p 3306:3306 mysql:8.4
MYSQL_HOST=127.0.0.1 MYSQL_PASSWORD=root pytest tests/test_mysql_oracle.py

中国語の説明

AI コーディングエージェント向けの MySQL 変更安全性レビューです。エージェントはマイグレーションの実行前に review_migration を呼び出し、 safe / review / block の判定と、各リスクの行番号、本番環境への影響、安全な記述方法を取得します。 ルールは DBA の経験に基づいて記述されており、結果は再現可能です。

ライセンス

Apache-2.0