mysql-audit
Provides deterministic safety review for MySQL schema changes and queries, using supplied schema definitions and table statistics to flag risky migrations, DDL/DML operations, and produce safe/review/block verdicts.
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
blockit 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.
Related MCP server: migrate-mcp
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 fromDROP/TRUNCATE/RENAME, missing rollbacks and backups.Data changes:
UPDATE/DELETEwithoutWHERE, unbatched backfills,LIMITwithoutORDER BY, statements that stop replication (sql_log_bin = 0).Queries:
WHERE/JOINcolumns 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:
Surface | Who uses it | What it does |
MCP server | Claude Code, Cursor, Windsurf, Claude Desktop and other agents | The agent calls |
| Developers and DBAs | Review files by hand or in any CI; exit code 0 / 1 / 2 |
GitHub Action | Teams | Reviews each pull request's migrations, annotates lines, comments, fails on |
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.sqlExample 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.gz2. Let your AI agent use it (Claude Code)
claude mcp add mysql-audit --scope user -- uvx mysql-audit-ai-agent@latestFrom 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 ... ✓ ConnectedRestart 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"] }
}
}Client | Config file |
Cursor |
|
Windsurf |
|
Claude Desktop (macOS) |
|
Claude Desktop (Windows) |
|
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-agentin 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 usemysql-audit(see Command line) to review files yourself, for exampleuvx --from mysql-audit-ai-agent mysql-audit migration.sql.
Tools
Tool | Arguments | Returns |
|
| Verdict and findings for DDL, migration scripts and bulk writes |
|
| Verdict and findings for queries the application will run |
|
| SQL injection findings in application source |
|
| Pre-deploy SQL to run on the primary |
|
| Why the rule matters and a safe example |
| Every rule with its id, title and default severity |
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]Option | Meaning |
| SQL files to review; reads stdin when omitted |
| Current |
| JSON table sizes, |
| Target server, e.g. |
| Free space on the server's data volume; with byte sizes enables L17 |
| Settings file (default: the nearest |
| Machine-readable output |
| Color text output: |
| The files are application code: check for SQL injection |
| Print pre-deploy SQL for these migrations instead of reviewing them |
| Print the installed 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 checksExit 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
ID | Checks | Default | Needs |
L01 | DDL without explicit | warn / block | |
L02 | Column changes that force a table copy: type change, VARCHAR shrink or crossing 255 bytes, ENUM reorder, charset conversion, dropping the PK, adding a STORED generated column | block | schema for exact answers |
L03 | Row-touching DDL on a large table: use gh-ost / pt-online-schema-change | warn | stats |
L04 | DDL without a short | warn | |
L05 |
| block | |
L06 | UPDATE / DELETE / INSERT ... SELECT over a large table in one transaction (replication lag) | warn | stats |
L07 |
| block | |
L08 |
| block / warn | |
L09 | Backfill not limited to a key range or batch size | warn / info | |
L10 | Auto-increment column smaller than BIGINT; | warn | |
L11 |
| warn | schema |
L12 | SQL built by f-strings, template literals, concatenation, | block | source code |
L13 |
| block / warn | |
L14 |
| warn | |
L15 |
| warn | |
L16 |
| block / warn | |
L17 | A table rebuild needs more free disk than the server has (under 1.5× the table size warns) | block / warn | stats with bytes, free disk |
L18 | A risky change with no rollback; a | warn |
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 TABLEstatements (SHOW CREATE TABLE, ormysqldump --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:SELECT JSON_OBJECTAGG(table_name, JSON_OBJECT( 'rows', table_rows, 'data_bytes', data_length, 'index_bytes', index_length)) FROM information_schema.tables WHERE 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, fromdf -h /var/lib/mysqlon the host or your cloud console (RDS / Aurora: theFreeStorageSpacemetric). 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 120Project 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 file
stats = "db/table_stats.json" # output of the stats query above
free_disk_gb = 120The 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.sql
mysql your_db < preflight.sqlThe 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
--rollbacklines;a sibling file:
*.down.sqlnext to*.up.sql(golang-migrate), orU<version>__*.sqlnext toV<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.yml
name: MySQL Audit
on: [pull_request, pull_request_review] # the review event lets a DBA approval re-run it
permissions:
contents: read
pull-requests: write # for the summary comment
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: jimmyjan0824/mysql_audit_ai_agent@v0.3.3
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 neverInput | Default | Meaning |
|
| Glob patterns (comma or newline separated) of migration files |
| File with the current | |
| JSON table sizes; enables the large-table rules | |
| 8.0.29+ | Target MySQL version |
| Free space on the data volume; with byte stats enables L17 | |
| GitHub users whose approving review lets a failing check pass | |
| Glob patterns of application code to check for SQL injection | |
|
| In pull requests, review only the files the pull request adds or changes |
|
| Fail the check at |
|
| Post and keep updating one summary comment |
|
| Token used to list files and comment |
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:
Installed with | Upgrade |
|
|
|
|
| uvx reuses its cached copy; use |
GitHub Action | change the |
Troubleshooting
Problem | Fix |
| Expected: it is the MCP server waiting for a client. Press Ctrl+C. Add it to your agent's MCP config, and use |
| Install in a virtual environment: |
Claude Code | uvx is not installed or not on Claude Code's PATH. Install uv if |
Desktop app shows | Use the full path from |
First start of the MCP server times out | The first run downloads the package. Run |
Results differ from this README | You may have an old cached copy; see Version and upgrades |
A rule fires on a table you know is small | Pass |
A result is wrong | Please use the report form |
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 runs
hash -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_agent
cd mysql_audit_ai_agent
python3 -m venv .venv && source .venv/bin/activate
pip install mysql-audit-ai-agent
python trial/run.py # expected vs actual verdict for each example
python trial/run.py -v # plus every findingWith 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_agent
cd mysql_audit_ai_agent
pip install -e ".[dev]"
pytestEvery 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-mcptests/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.4
MYSQL_HOST=127.0.0.1 MYSQL_PASSWORD=root pytest tests/test_mysql_oracle.pyProject layout
Path | Contents |
| Splits the script, runs every rule, builds the report |
| One module per rule family (locking, data safety, queries, injection, rollback, ...) |
| The |
| The MCP server ( |
| The GitHub Action |
| Pre-deploy SQL |
|
|
| Unit tests and the real-MySQL checks |
| DBA trial kit |
| Claude Desktop bundle and MCP Registry metadata |
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
Available Tools
6 toolsexplain_ruleC
Explain one rule (e.g. "L02"): why it matters and a safe example.
Inputs: rule_id (required).
list_rulesA
List every rule this server checks, with its id, title and default severity.
Inputs: no named parameters. Returns: result
preflight_checksA
SQL for the user (or DBA) to run on the primary right before deploying a migration: long transactions, long queries and metadata locks on the tables it touches, current table sizes, and how to check replica lag. Each query returns rows only when the deploy should wait. This tool does not connect to the database; hand the SQL to the user.
Args: sql: The migration that is about to run. mysql_version: Optional server version, e.g. "5.7.44"; picks SHOW SLAVE / REPLICA STATUS.
Inputs: sql (required), mysql_version.
review_codeA
Check application source code (Python, JS/TS, PHP, Go, Java) for SQL built by string interpolation or concatenation, i.e. SQL injection.
Returns a verdict (safe / block) and findings with line and the parameterized fix.
Inputs: code (required).
review_migrationA
Review MySQL DDL or a migration script for locking, data-loss and replication risks.
Args: sql: The SQL to run, one or more statements separated by semicolons. schema: Optional CREATE TABLE statements for the tables involved (e.g. from SHOW CREATE TABLE). Makes column-type and index checks exact. stats: Optional size per table from information_schema.tables: a row count ({"orders": 25000000}) or {"orders": {"rows": 25000000, "data_bytes": <data_length>, "index_bytes": <index_length>}}. Large = 1M rows or 5 GB. mysql_version: Optional target server version, e.g. "8.0.28", "8.4.3" or "aurora-3.04" (SELECT VERSION()). Older servers copy the table for more column changes. Without it, 8.0.29 or later is assumed. free_disk_gb: Optional free space on the server's data volume, in GB. With byte sizes in stats, a table rebuild that does not fit is blocked. rollback_sql: Optional down migration kept in a separate file (e.g. a golang-migrate .down.sql or Flyway U__ file). Down sections and --rollback lines inside sql are found without it.
Returns a verdict (safe / review / block) and findings with line, impact and fix.
Inputs: sql (required), stats, schema, free_disk_gb, +2 more.
review_queryB
Review queries an application will run (SELECT / UPDATE / DELETE / INSERT) for missing indexes, unbatched writes and unsafe UPDATE/DELETE. Pass schema for index checks.
Returns a verdict (safe / review / block) and findings with line, impact and fix.
Inputs: sql (required), stats, schema, mysql_version.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The three review tools are separated by input type (DDL/migration, DML queries, application source code), and their descriptions make these boundaries explicit. preflight_checks, explain_rule and list_rules are clearly distinct. Minor residual risk that an agent passes query text to review_code or vice versa, but descriptions mitigate this well.
All names are snake_case and mostly follow a verb_noun pattern (review_migration, review_query, review_code, explain_rule, list_rules). preflight_checks is the one noun-only outlier, but it is still readable and consistent in style.
Six tools is well-scoped for an audit/lint server: three analysis entry points, one pre-deploy checklist generator, and two rule-discovery helpers. Each tool has a clear reason to exist with no filler.
The surface covers the full audit lifecycle: migration review, query review, injection scanning, pre-deploy checks, and rule discovery/explanation. The only gaps are that nothing connects to the database itself (a deliberate design choice stated in preflight_checks) and there is no way to inspect live schema or existing table state directly.
Maintenance
Related MCP Connectors
Review your AI agent's database changes on your schema, with plain-language risk, before they run.
Detects database migration table locks, terraform cost leaks, and OWASP API flaws.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
SQL validation, formatting, parsing, metadata extraction, linting, and security analysis.
Related MCP Servers
- AlicenseAqualityDmaintenanceAnalyzes database migrations for risks like lock contention and data loss before they run. Supports Flyway and Liquibase formats, providing risk scores and rollback generation.694 npmMIT
- AlicenseAqualityBmaintenanceEnables safe database migration workflows by detecting frameworks, reviewing migration risk and drift, generating migration files with explicit approval, and providing rollback guidance—without ever applying migrations or executing rollbacks.75 npm1MIT
- AlicenseAqualityBmaintenanceOffline PostgreSQL diagnostics: reviews SQL, risky migrations, candidate indexes and EXPLAIN JSON plans without database credentials or executing statements.5232 npmMIT
- AlicenseBqualityCmaintenanceEnables AI coding agents to perform deterministic database architecture audits and performance engineering for PostgreSQL and MySQL, covering migration analysis with schema health scoring, ESR-based composite index recommendations, N+1 query detection, EXPLAIN plan diagnosis, transaction and deadlock analysis, partitioning and archival design, and capacity or configuration tuning. It also generates phased Expand & Contract runbooks that turn blocking DDL into zero-downtime production migrations.8MIT