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 environmentmysql-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 terminalclaude mcp remove mysql-audit                          # re-add it with the full path to uvxclaude mcp add mysql-audit --scope user -- "$(which uvx)" mysql-audit-ai-agent@latestclaude 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.jsonmysql-audit db/migrate/*.sql --mysql-version 8.0.28 --format jsonecho "UPDATE users SET status = 0;" | mysql-audit          # from stdinmysql-audit --code app/models/user.py                      # SQL injection checkmysql-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

Tables created earlier in the same script are treated as empty, so DDL on them is not flagged. mysql-audit cannot explain a rule by itself; ask the agent ("explain rule L03") or read src/mysql_audit/rules/.

Inputs that make results exact

Without extra input the review is conservative: it cannot tell a 100-row table from a 100-million-row one, or what type a column has now. Three inputs fix that. None of them needs a connection from the tool to your database; you export them once.

• schema: the current CREATE TABLE statements (SHOW CREATE TABLE, or mysqldump --no-data --skip-comments your_db > schema.sql).

• stats: approximate size per table from information_schema.tables, either row counts ({"orders": 25000000}) or rows and bytes:

  sql

  SELECT JSON_OBJECTAGG(table_name, JSON_OBJECT(         'rows', table_rows, 'data_bytes', data_length, 'index_bytes', index_length))FROM information_schema.tablesWHERE table_schema = DATABASE() AND table_type = 'BASE TABLE';

  From a shell: mysql -N -e "<the query above>" your_db > stats.json. A table counts as large at 1,000,000 rows or 5 GB (data plus indexes), and as small under 10,000 rows. With bytes, L03 states how much free space a rebuild needs.

• free disk (--free-disk-gb, free_disk_gb): free space on the server's data volume, from df -h /var/lib/mysql on the host or your cloud console (RDS / Aurora: the FreeStorageSpace metric). With table bytes it enables L17.

MySQL version

Which ALTERs run INSTANT depends on the server version: 5.7 has no INSTANT, 8.0.12–8.0.28 only adds columns at the end instantly, and 8.0.29+ also adds anywhere and drops columns instantly. Without a version the tool assumes 8.0.29+ and says so in the result. Pass the version you deploy to (SELECT VERSION();), for example 8.0.28, 5.7.44 or aurora-3.04:

mysql-audit migration.sql --mysql-version 8.0.28 --free-disk-gb 120

Project settings (.mysql-audit.toml)

To avoid repeating options, put a .mysql-audit.toml at the repository root. The CLI, the MCP server and the GitHub Action all read it (searching upward from the current directory, stopping at the .git folder); options given on the command line or in the tool call win.

mysql_version = "8.0.28"schema = "db/schema.sql"        # paths are relative to this filestats = "db/table_stats.json"   # output of the stats query abovefree_disk_gb = 120

The MYSQL_AUDIT_VERSION environment variable overrides mysql_version for the CLI and the MCP server, for example claude mcp add mysql-audit -e MYSQL_AUDIT_VERSION=8.0.28 -- uvx mysql-audit-ai-agent.

Pre-deploy checks

The review never connects to your database. What only the live server knows (open transactions, metadata locks, replica lag) is checked by SQL you run on the primary right before deploying:

mysql-audit migration.sql --preflight > preflight.sqlmysql your_db < preflight.sql

The queries are scoped to the tables the migration touches, and each returns rows only when the deploy should wait: transactions open longer than 10 seconds, statements on those tables running 10 seconds or more, sessions holding or waiting for their metadata locks, and tables that are large right now. The script also says how to check that every replica lags 10 seconds or less. No rows from every query means go. CI runs it against MySQL 5.7, 8.0.28, 8.0 and 8.4, with and without a blocking transaction. Agents get the same SQL from the preflight_checks tool.

Rollbacks and backups

L18 warns when a migration with review or block findings has no way back, and when it deletes data without saying where the backup is. It accepts any of these as a rollback:

• a down section in the same file: -- +goose Down, -- migrate:down (dbmate), -- +migrate Down (sql-migrate);
• Liquibase --rollback lines;
• a sibling file: *.down.sql next to *.up.sql (golang-migrate), or U<version>__*.sql next to V<version>__*.sql (Flyway);
• for a one-off script, a note: -- rollback: <what to run>.

A backup is noted with -- backup: <where it is>, for example -- backup: s3://db-backups/shop/orders_2026-10-28.sql.gz. Down migrations are not reviewed as changes themselves.

GitHub Action

Reviews the migrations each pull request adds or changes, annotates the lines in the diff, keeps one summary comment on the pull request up to date, and fails the check on block.

# .github/workflows/mysql-audit.ymlname: MySQL Auditon: [pull_request, pull_request_review]   # the review event lets a DBA approval re-run itpermissions:  contents: read  pull-requests: write   # for the summary commentjobs:  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          # mysql-version: 8.0.28         # optional; .mysql-audit.toml also works          # free-disk-gb: 120             # optional, with byte stats enables L17          # dba-approvers: alice,bob      # optional, see below          # code-paths: app/**/*.py       # optional SQL injection check          # fail-on: review               # block (default), review or never

When the result is review or block, the comment ends with a pre-deploy checklist and the preflight SQL for the changed migrations.

DBA approval. Some blocked changes are fine after a DBA has looked, for example a DROP COLUMN the application stopped using two releases ago. List the DBAs in dba-approvers: when one of them approves the pull request, the check passes. The approval must be on the latest commit, so a later push needs a new one, and a later "request changes" from the same person withdraws it. A ticked checkbox would not do here, because anyone who can edit the pull request can tick it.

Rollbacks. Down migrations are not reviewed as changes: *.down.sql (golang-migrate) and U<version>__*.sql (Flyway) count as the rollback of their up file, and so do down sections (-- +goose Down, -- migrate:down, -- +migrate Down) and Liquibase --rollback lines.

Version and upgrades

mysql-audit --version prints the installed version (mysql-audit-ai-agent --version for the MCP server). To upgrade:

Troubleshooting

Upgraded, but mysql-audit still runs the old version? (For example, --version is rejected as an unrecognized argument.) The shell is finding another copy first, such as an older uv tool install in ~/.local/bin, or it still remembers the old path:

which -a mysql-audit   # every copy on PATH; the first one is what runshash -r                # forget remembered paths (zsh: rehash)

If the first copy is not the one you upgraded, activate that environment (source .venv/bin/activate), or upgrade or remove the other copy (uv tool upgrade mysql-audit-ai-agent / uv tool uninstall mysql-audit-ai-agent). .venv/bin/mysql-audit --version checks a venv's copy directly.

DBA trial kit

trial/ has 24 example migrations and 2 code samples on a small shop schema (orders 25M rows, users 2.4M), each marked with the verdict it should get. Every example also runs on MySQL 8.0 and 8.4 in CI. Guides: English · 繁體中文.

git clone https://github.com/jimmyjan0824/mysql_audit_ai_agentcd mysql_audit_ai_agentpython3 -m venv .venv && source .venv/bin/activatepip install mysql-audit-ai-agentpython trial/run.py        # expected vs actual verdict for each examplepython trial/run.py -v     # plus every finding

With uv instead: uv run --no-project --with mysql-audit-ai-agent python trial/run.py.

Found a wrong result (a false alarm, a missed risk, or a fix that doesn't work)? Please use the report form.

Development

git clone https://github.com/jimmyjan0824/mysql_audit_ai_agentcd mysql_audit_ai_agentpip install -e ".[dev]"pytest

Every rule has positive and negative test cases under tests/.

To try your local changes in Claude Code without publishing, point it at your checkout. Each session runs the code as it is now; after an edit, restart Claude Code or reconnect in /mcp.

claude mcp add mysql-audit-dev -- uv --directory /path/to/mysql_audit_ai_agent run mysql-audit-mcp

tests/test_mysql_oracle.py checks the rules against a real server: each ALTER is run with ALGORITHM=INPLACE, LOCK=NONE, and MySQL's refusal (or not) must match the rule's verdict. CI runs it on MySQL 8.0 and 8.4. tests/test_mysql_versions.py checks the version-dependent INSTANT judgment the same way on 5.7, 8.0.28 and 8.4. Locally:

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

Project layout

Releasing

Bump the version in pyproject.toml, src/mysql_audit/__init__.py, server.json (twice), mcpb/manifest.json and the Action example in this README and in README.zh-TW.md, merge, then publish a GitHub release tagged vX.Y.Z on main. The Release workflow checks that the tag matches every version field, then publishes to PyPI and the MCP Registry and attaches the .mcpb bundle.

License

Apache-2.0