MySQL Audit

mysql_audit_ai_agent

English | 繁體中文

MySQL schema-change safety review for AI coding agents.

Before Claude Code, Cursor or another agent runs a migration, it sends the SQL to review_migration and gets back a verdict (safe / review / block) plus, for every risk, the line, what will happen in production, and a safe way to write it. The checks are deterministic rules written from DBA experience, not another LLM guess.

Status: beta. Every rule about server behavior is checked against real MySQL in CI. DBAs: try the trial kit and report wrong results.

Contents: Why · What it checks · Quick start · Use with an AI agent (MCP) · Command line · Rules · Inputs that make results exact · Pre-deploy checks · Rollbacks and backups · GitHub Action · Version and upgrades · Troubleshooting · DBA trial kit · Development

Why

AI coding agents write and run migrations quickly, but the SQL that looks correct is often the SQL that takes production down: an ALTER TABLE that silently copies a 25-million-row table and blocks writes, a column type change that forces a full rebuild, a DROP COLUMN the previous release still reads, an UPDATE without WHERE, a backfill that leaves every replica minutes behind. These are the incidents a DBA catches in review, and an agent has no DBA in the loop.

MySQL Audit puts that review in front of the agent:

• Before it runs, not after. The agent calls the review tool before executing a migration, query or SQL-building code. On block it rewrites and reviews again.
• Deterministic. The same SQL always gets the same verdict. Each rule that depends on server behavior is tested against real MySQL 5.7, 8.0 and 8.4 in CI.
• Actionable. Every finding has the line, the production impact and a concrete fix (for example ALGORITHM=INSTANT, gh-ost, batching by primary key, expand and contract).
• Local and private. It never connects to your database and runs entirely on your machine. Your SQL and data never leave it.

What it checks

• Migrations and DDL: table copies and write locks (Online DDL ALGORITHM / LOCK), version-dependent INSTANT changes, metadata-lock pile-ups, foreign keys, unique keys, large tables, free disk for rebuilds, data loss from DROP / TRUNCATE / RENAME, missing rollbacks and backups.
• Data changes: UPDATE / DELETE without WHERE, unbatched backfills, LIMIT without ORDER BY, statements that stop replication (sql_log_bin = 0).
• Queries: WHERE / JOIN columns no index can use.
• Schema design: tables without a primary key, auto-increment columns that will overflow, utf8mb3.
• Security: SQL injection in application code (Python, JS/TS, PHP, Go, Java) and dangerous GRANTs.

It is used in three ways:

Quick start

You need Python 3.10 or later, or uv (uv brings its own Python).

1. Review a file from the command line

pip install mysql-audit-ai-agent          # in a virtual environment

mysql-audit migration.sql

or without installing anything, with uv:

uvx --from mysql-audit-ai-agent mysql-audit migration.sql

Example output:

trial/migrations/12_drop_column.sql: BLOCK (2 statements)

line 5 [block] L07: This statement drops column coupon_code. fix: Use expand and contract: ship code that no longer uses the column or table first, take a backup, then drop it in a later release. ... line 5 [warn] L18: This migration deletes data, and the file does not say where the backup is. fix: Back up what is deleted first ... and note it in the file: -- backup: s3://bucket/orders_2026-10-28.sql.gz

2. Let your AI agent use it (Claude Code)

claude mcp add mysql-audit --scope user -- uvx mysql-audit-ai-agent@latest

From then on, Claude reviews migrations before running them. Other agents: see Use with an AI agent.

3. Review every pull request with the GitHub Action.

Use with an AI agent (MCP)

Requires uv. The server runs locally over stdio; your SQL never leaves your machine.

Claude Code

claude mcp add mysql-audit --scope user -- uvx mysql-audit-ai-agent@latest

--scope user makes it available in every project. --scope project writes it to the project's .mcp.json instead, so everyone who clones the repo gets it. Check that it is connected with claude mcp list (it should show mysql-audit ... ✓ Connected), or type /mcp inside Claude Code to see the tools. Then ask Claude to review a migration, or just let it run one: it calls review_migration on its own. Remove it with claude mcp remove mysql-audit.

`/mcp` says `Failed to reconnect to mysql-audit: ENOENT`? Claude Code cannot find the uvx command: uv is not installed, or it is installed in a folder that is not on the PATH Claude Code was started with.

which uvx                                              # where is uvx?

curl -LsSf https://astral.sh/uv/install.sh | sh # if not found: install uv, then open a new terminal claude mcp remove mysql-audit # re-add it with the full path to uvx claude mcp add mysql-audit --scope user -- "$(which uvx)" mysql-audit-ai-agent@latest claude mcp list # should show mysql-audit ... ✓ Connected

Restart Claude Code (or reconnect in /mcp) afterwards. The first start downloads the package and can take a few seconds.

Cursor, Windsurf, Claude Desktop and other MCP clients (mcp.json / claude_desktop_config.json):

{

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

Restart the client after editing. If a desktop app reports spawn uvx ENOENT, it cannot find uvx: replace "uvx" with the full path from which uvx (Windows: where uvx).

Claude Desktop, one click: download mysql-audit.mcpb from the latest release and open it.

**Running uvx mysql-audit-ai-agent in a terminal prints nothing and seems to hang. That is

expected:** it is the MCP server, waiting for an MCP client to talk to it over stdin. Press

Ctrl+C to leave. Put the command in your client's MCP config as above, and use

mysql-audit (see Command line) to review files yourself, for example

uvx --from mysql-audit-ai-agent mysql-audit migration.sql.

Tools

Arguments the call leaves out are read from .mysql-audit.toml. Example prompts to try: "Add a nickname column to users", "Drop the note column from orders", "Check this Python for SQL injection: cur.execute(f\"... {email}\")", "Explain mysql-audit rule L03".

In our agent evaluation Claude Code called the tool on its own in 10 of 10 migration tasks, with no extra prompt.

Command line

mysql-audit [files ...] [--schema FILE] [--stats FILE] [--mysql-version VERSION]

[--free-disk-gb GB] [--config FILE] [--format text|json] [--color auto|always|never] [--code] [--preflight] [--version]

Examples:

mysql-audit db/migrate/20261027_add_index.sql --schema schema.sql --stats stats.json

mysql-audit db/migrate/*.sql --mysql-version 8.0.28 --format json echo "UPDATE users SET status = 0;" | mysql-audit # from stdin mysql-audit --code app/models/user.py # SQL injection check mysql-audit migration.sql --preflight > preflight.sql # pre-deploy checks

Exit code: 0 = safe, 1 = review, 2 = block, so it can gate any CI.

Verdicts: block means do not run it as written; review means it can run but a person should read the findings first; safe means no findings at warn level or above. Each finding has a severity (block, warn, info), a line number, the impact and a fix.

Rules

| L07 | DROP / TRUNCATE / RENAME of