MySQL AIops

MySQL AIops

免責事項：コミュニティが保守するオープンソースプロジェクトです。Oracle Corporation または MariaDB Foundation とは提携しておらず、承認や支援も受けていません。「MySQL」は Oracle Corporation の商標、「MariaDB」は MariaDB plc の商標です。すべての製品名および商標名は、それぞれの所有者に帰属します。MIT ライセンスで提供されています。

MySQL 8.x および MariaDB 10.6 以降の DBA 運用向けに、ガバナンスを備えた AI 運用機能を提供します。PyMySQL でサーバーに接続し、information_schema ／ performance_schema を読み取ります。さらに、統合監査ログ、トークン／暴走予算ガード、取り消しトークンの記録、説明的なリスクティアラベルを備えた組み込みのガバナンスハーネスを搭載しています。サーバーのフレーバー（mysql または mariadb）は version() から検出され、フレーバーに応じたステートメント（SHOW REPLICA STATUS と SHOW SLAVE STATUS）は自動的に切り替わります。

できること

4 つの主要な分析機能と、それらを支えるガード付きの読み取り／書き込み機能を備えています。

• スロークエリの根本原因分析（RCA） — events_statements_summary_by_digest の中から最も問題の大きいエントリを取得し（任意で EXPLAIN FORMAT=JSON の実行計画も取得）、その数値（インデックス未使用率（SUM_NO_INDEX_USED）、ロック時間の割合、調査行数／返却行数の比率、一時ディスクへのスピル、呼び出し回数、実行計画のアクセス方式）を、根拠のある原因と具体的な対処方法に結び付けます。各分析結果にはブラックボックス的な判定ではなく、測定値が示されます。
• InnoDB のロック待ちとデッドロックチェーンの根本原因分析（RCA） — performance_schema.data_lock_waits（MariaDB では information_schema.innodb_lock_waits）から待機関係のツリーを構築し、ルートブロッカー（他の処理をブロックし、何も待機していない処理）を特定します。また、SHOW ENGINE INNODB STATUS から直近のデッドロックを解析します。
• レプリケーション遅延の根本原因分析（RCA） — レプリカの IO／SQL スレッドの状態、Seconds_Behind_Source、エラーフィールドを、根拠のある原因と対処方法（IO スレッドの停止、アプライヤーのステートメント失敗、アプライヤーの遅延、意図的な SQL_Delay）に結び付けます。
• テーブル断片化の分析 — information_schema.tables の再利用可能な data_free に基づいてテーブルをランク付けし、根拠を示した OPTIMIZE TABLE の候補を提示します。

動作する機能

• CLI（mysql-aiops ...）：init、overview、server、activity、query、index、table、repl、analyze、remediate、secret、doctor、mcp。
• MCP サーバー（mysql-aiops mcp または mysql-aiops-mcp）：35 個のツール（読み取り 26 個、書き込み 9 個）を提供し、すべてにバンドルされた @governed_tool ハーネスが適用されます。
• 暗号化された認証情報：アカウントのパスワードは、暗号化ストア ~/.mysql-aiops/secrets.enc（Fernet + scrypt）に保存されます。ディスク上に平文で保存されることはありません。 MYSQL_AIOPS_MASTER_PASSWORD のマスターパスワード（MCP／CI）または対話形式のプロンプト（CLI）でロックを解除します。
• 可逆性：変更を伴う書き込みでは、最初に実際の変更前状態を取得し、正確な逆操作を記録します。create_index ↔ drop_index のように対応し、drop_index では SHOW CREATE TABLE からインデックス定義を取得して、取り消し時に正確に再作成します。set_global_variable では SHOW GLOBAL VARIABLES から以前の値を取得し、取り消し時に元の値へ戻します。取り消し不可能な操作（kill_session、kill_query、optimize_table、analyze_table、reset_query_stats）では、監査用に以前の状態を記録しますが、取り消し操作は宣言しません。
• 安全性：状態を変更する CLI 操作はすべて --dry-run に対応し、二重の確認が必要です。書き込みを行う MCP ツールはすべて dry_run によるプレビューを受け取ります。パラメーター化できない識別子（スキーマ名／テーブル名／インデックス名／カラム名／変数名）は、すべて厳格な文字セットで検証したうえでバッククォートで囲みます。すべての値はクエリパラメーターとしてバインドされます。

このツールが判断すること、判断しないこと

MySQL / MariaDB の DBA 操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それを判断するのはエージェント、または接続に使用するアカウントの権限です。SELECT / PROCESS / REPLICATION CLIENT のみが許可され、書き込み権限（INSERT/UPDATE/DELETE/DDL）がない MySQL/MariaDB アカウントを指定すれば、書き込みは権限を実際に管理する場所であるサーバー側で失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定が必要な承認ゲートもありません。このツールが保証するのは、何もひそかに実行されないことです。MCP 経由でも CLI 経由でも、すべての呼び出しが ~/.mysql-aiops/audit.db に監査行として記録され、破壊的な書き込みについては変更前の状態を取得し、可能な場合は元に戻す操作も記録します。

各ツールは risk_level を宣言し、監査行に説明用の段階（none/confirm/review）として記録します。これにより、レビュー担当者はリスクの高い削除の行をひと目で確認できます。これはラベルであり、ゲートではありません。

小規模なモデルやローカルモデルを実行していますか？agent-guardrails.md をご覧ください。このツールが現在適用しているガードレール（プロンプトの予算を使って改めて指示する必要がなくなります）と、残る項目に使えるすぐに利用可能なシステムプロンプトが記載されています。

機能マトリックス（MCP ツール 35 個）

分野	ツール	数	読み取り／書き込み
概要	overview	1	読み取り
サーバー	server_version、show_variables、show_status、list_databases、list_engines、connection_stats	6	読み取り
アクティビティ	list_sessions、long_running_queries、list_transactions、lock_waits	4	読み取り
クエリ	top_queries、explain_query	2	読み取り
インデックス	unused_indexes、redundant_indexes、index_stats	3	読み取り
テーブル	table_sizes、table_fragmentation、table_status	3	読み取り
レプリケーション	replica_status、binlog_status	2	読み取り
分析（主力機能）	slow_query_rca、lock_wait_rca、replication_lag_rca、fragmentation_analysis	4	読み取り
書き込み	kill_session、kill_query、drop_index	3	書き込み（高）
	optimize_table、analyze_table、create_index、set_global_variable、reset_query_stats	5	書き込み（中）
元に戻す	undo_list、undo_apply	2	読み取り／書き込み

主力の分析機能は、純粋なオフライン分析用にレコードを注入することも、設定済みのターゲットからライブデータを取得することもできます。top_queries／slow_query_rca には performance_schema=ON が必要です。読み取り用アカウントには、performance_schema に対する PROCESS、REPLICATION CLIENT、SELECT が必要です。

サポート範囲

プラットフォーム	状況
MySQL 8.0 / 8.4	対応対象（SHOW REPLICA STATUS、performance_schema.data_lock_waits）
MariaDB 10.6+ / 11.x	対応対象（SHOW SLAVE STATUS、information_schema.innodb_lock_waits）
MySQL 5.7 以前	対象外（EOL。8.0 以前のダイジェスト／ロックビューは未テスト）
クラウド管理型 MySQL（RDS/Aurora/Cloud SQL の各種サービス）	ワイヤー互換の読み取りは動作するはずです。管理サービスの制限（KILL、SET GLOBAL）が適用されます。未テストです。

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントにスキルと MCP サーバーの両方が追加されます。

/plugin marketplace add AIops-tools/marketplace
/plugin install mysql-aiops@aiops-tools

MCP サーバーは uv で取得され、このプラグインが指定するパッケージバージョンに固定されます。そのため、監査行を、それを書き込んだコードまでたどることができます。認証情報は引き続き mysql-aiops init で設定します。詳しくは以下をご覧ください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、インストールするとスキルと MCP サーバーをまとめて導入できます。

openclaw plugins install clawhub:@zw008/mysql-aiops
openclaw skills info mysql-aiops          # expect: Visible to model: yes

その後、OpenClaw ゲートウェイを再起動してプラグインを読み込ませてください。MCP サーバーは uv を使って取得され、この正確なリリースに固定されています。そのため、uvx が PATH 上に必要です。これがない場合、スキルはインストールされますが、Visible to model: no と表示されます。認証情報は以下と同じ方法で設定します。

CLI またはスタンドアロン MCP サーバーとして

uv tool install mysql-aiops             # or: pipx install mysql-aiops
mysql-aiops init                        # wizard: add a target + store the password (encrypted)
mysql-aiops doctor                      # verify config, secrets, connectivity, flavor, perf-schema
mysql-aiops overview                    # one-shot server health snapshot
mysql-aiops analyze slow-query          # RCA the worst statement digest
mysql-aiops analyze fragmentation       # OPTIMIZE TABLE candidates

MCP サーバー（stdio）として実行します。

export MYSQL_AIOPS_MASTER_PASSWORD=...  # unlock secrets non-interactively
mysql-aiops-mcp

そのパスワードの保存先：エクスポートした変数は、このシェルが起動するすべてのプロセスから読み取り可能で、シェルの履歴にも記録されます。共有ホストや長時間稼働するホストでは、対話型プロンプトを使うか、必要なコマンドの実行中だけシークレットマネージャーから渡すことをおすすめします。

Claude Desktop／MCP クライアントの設定：

{
  "mcpServers": {
    "mysql-aiops": {
      "command": "uvx",
      "args": ["--from", "mysql-aiops", "mysql-aiops-mcp"],
      "env": { "MYSQL_AIOPS_MASTER_PASSWORD": "your-master-password" }
    }
  }
}

env ブロックに関する注意：上記の env ブロックだけが MCP サーバーに渡される環境です。GUI から起動したクライアントは、シェルのプロファイルを継承しません。MYSQL_AIOPS_MASTER_PASSWORD（および使用する場合は MYSQL_AIOPS_HOME／MYSQL_AUDIT_APPROVED_BY）をそこに設定してください。設定しないと、サーバーはシークレットストアのロックを解除できません。

ガバナンス

すべての MCP ツールは、同梱の @governed_tool ハーネスを経由します。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスク層、オペレーターが指定した承認者／理由があればその情報）が ~/.mysql-aiops/audit.db に記録されます（MYSQL_AIOPS_HOME で保存先を変更できます）。CLI も MCP 経由の場合と同じレコードを書き込むため、監査されないエントリーポイントはありません。
• 暴走防止ガード — 認可ゲートではなく、安全策として機能します。同じ呼び出しを短時間に繰り返すと、サーキットブレーカーが作動します。MYSQL_RUNAWAY_MAX=0 で無効化できます。必要に応じて MYSQL_MAX_TOOL_CALLS／MYSQL_MAX_TOOL_SECONDS で上限を設定できます。
• 取り消し記録 — 元に戻せる書き込みでは、取得した変更前の状態に基づいて逆操作の記述子を記録します。
• リスク層 — risk_level から導出され、監査レコードに記載される説明用のラベルです。何も制限しません。

対象範囲

これは AIops-tools ファミリー（監査＋予算＋取り消し＋リスク層を備えたガバナンス付き AI 運用）の MySQL／MariaDB DBA 運用向けメンバーです。PostgreSQL には使用しないでください。postgres-aiops を使用してください。OT／産業用エッジにも使用しないでください。別系統の industrial-aiops を参照してください。また、アプリケーションスキーマの移行や ORM 管理にも使用しないでください。

必要な機能がありませんか？

対象範囲は、MySQL のカタログやメンテナンス機能のうち、意図的に厳選した一部です。ビュー、メトリクス、メンテナンスコマンドが不足していますか？issue または PR を作成してください。貢献を歓迎します。不足機能があれば issue／PR を作成してください。コメントも歓迎します。

検証状況

MySQL 8.4.10 および MariaDB 11.8.8 で実環境検証済み（2026-07-19/20）。 接続、読み取り処理、実際の全件スキャンを対象にした analyze slow-query、およびガバナンスの全工程（実際の create_index → 監査レコード → インデックスを実際に削除する取り消し）を実サーバーで実行しました。この実行で、モックテストでは検出できなかった実際のバグを発見し、修正しました。SUM() の集計結果が Decimal として返され、JSON にシリアライズできませんでした。

MariaDB の処理系も、実際の行競合を対象にした analyze lock-waits を含め、検証済みです（根本原因となったブロッカーと、計測された待機時間を正しく特定しました）。 実際のレプリカを使ったレプリケーションは未検証です。

docs/VERIFICATION.md には、検証した内容と未解決の項目が正確に記録されています。実環境での確認（接続、フレーバー、performance_schema、レプリカの役割）には、mysql-aiops doctor が最も手早い方法です。