MySQL Audit

mysql_audit_ai_agent

为 AI 编码 Agent 提供 MySQL 架构变更安全审查。

在 Claude Code、Cursor 或其他 Agent 执行迁移之前，它会将 SQL 发送给 review_migration，并获取判定结果（safe / review / block），以及每项风险对应的行号、生产环境中的影响和安全写法。 这些检查采用基于 DBA 经验编写的确定性规则，而不是另一个大模型的猜测。

状态：测试版。所有 12 条规则都已在 CI 中使用 MySQL 8.0 和 8.4 进行验证。DBA：请试用试用套件，并报告错误结果。

规则

ID	检查项	默认处理	需要
L01	DDL 未显式指定 ALGORITHM / LOCK；ALGORITHM=COPY、LOCK=SHARED/EXCLUSIVE	警告 / 阻止
L02	会强制复制表的列变更：类型变更、VARCHAR 缩短或跨越 255 字节、ENUM 重排、字符集转换、删除主键	阻止	需要架构信息才能给出精确结果
L03	对大表执行会触及行的 DDL：使用 gh-ost / pt-online-schema-change	警告	统计信息
L04	DDL 未设置较短的 SET SESSION lock_wait_timeout（元数据锁堆积）	警告
L05	foreign_key_checks=1 时执行 ADD FOREIGN KEY（仅 COPY）	阻止
L06	在一个事务中对大表执行 UPDATE / DELETE / INSERT ... SELECT（复制延迟）	警告	统计信息
L07	DROP / TRUNCATE / RENAME 列、表、数据库	阻止
L08	UPDATE / DELETE 未指定 WHERE；LIMIT 未指定 ORDER BY	阻止 / 警告
L09	回填未限制键范围或批量大小	警告 / 信息
L10	自增列小于 BIGINT；utf8 / utf8mb3	警告
L11	WHERE / JOIN 使用的列没有以其开头的索引	警告	架构信息
L12	使用 f 字符串、模板字面量、字符串拼接、% / .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 Agent 配合使用（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()。

在我们的 Agent 评估中，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

退出代码：0 表示安全，1 表示需要审查，2 表示阻止，因此可用于设置 CI 门禁。

GitHub Action

审查每个拉取请求新增或修改的迁移，在差异中标注对应行，持续更新拉取请求中的一条摘要评论，并在结果为 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 变更安全审查。代理在执行 migration 前呼叫 review_migration， 取得 safe / review / block 判定，以及每个风险的行号、线上影响与安全写法。 规则由 DBA 经历写成，结果可重复验证。

许可证

Apache-2.0