⚡ MySQL Advisor

Help & FAQ

How to collect diagnostics safely and get the most from MySQL Advisor.

How MySQL Advisor works

  1. Provide inputs. Paste or upload SHOW GLOBAL VARIABLES, SHOW GLOBAL STATUS, pt-summary, and/or pt-mysql-summary output in the matching tabs — or use Collect data from MySQL with read-only credentials so the tool can fetch variables and status for you (the connection is opened from the MySQL Advisor server, and the credentials are not stored — see the Security & Privacy notes below). You can also drag a .txt file onto the console; pasted output is recognized and routed to the right tab automatically, and the detected server version appears in the console header.
  2. Security verification. Enter the CAPTCHA code (required before analysis).
  3. Analyze. Click Analyze Configuration. The tool evaluates your inputs and shows an on-page report with findings and recommendations, grouped by category and ordered by severity.
  4. Export. Download the same report as HTML, Markdown, a Word document (.doc), or a ready-to-review my.cnf snippet of the suggested changes from the Analysis Results toolbar.

Just exploring? Click Try sample data in the input console to load example output from a demo MySQL 8.0 server and see a full analysis. For a guided tour of the UI, open the main tool and use How this works.

Using the API instead? Copy-paste commands to collect data and call the API. Jump to the API usage guide →

Beyond the analyzer: the toolbox

  1. my.cnf download. The my.cnf button in the results toolbar builds a [mysqld] snippet from the findings. Settings with a clear suggested value appear ready to paste; everything else is included as commented advice. Review each line before applying it.
  2. Upgrade advisor. The Upgrade page checks your SHOW GLOBAL VARIABLES output against MySQL 8.0, 8.4 LTS, or 9.x and flags variables that are deprecated, renamed, or removed at the target version. Client-side only.
  3. Schema advisor. The Schema page reviews CREATE TABLE statements or a mysqldump --no-data file for primary key design, duplicate and redundant indexes, foreign key compatibility, InnoDB row size and schema-level upgrade blockers. Definitions only, no rows.
  4. CLI client. cli/mysqladvisor.sh collects variables and status via the mysql client, calls the API with your key, and prints the Markdown report in the terminal. See the API usage guide for setup and examples.

FAQ — Collecting MySQL Diagnostic Data

All commands below are read-only unless explicitly stated. Safe to run on production systems.

No writes  ·  No locks  ·  No performance impact

Supported Technologies

Quick Checklist

□ pt-summary
□ pt-mysql-summary
□ SHOW GLOBAL VARIABLES
□ SHOW GLOBAL STATUS
□ Read-only MySQL user
□ schema.sql (Schema Advisor)

Variable Reference

Browse detailed documentation for all 115 MySQL variables checked by the advisor, including scope, defaults, severity levels, and tuning guidance.

Browse Variable Reference →
1

Collect pt-summary — server-level info

OS access Safe

pt-summary collects OS, hardware, kernel, and MySQL runtime metadata. It does not modify the system and is safe for production environments.

wget https://www.percona.com/get/pt-summary
chmod +x pt-summary
./pt-summary > server_name_$(date +%d%m%y)_pt-summary.txt

Alternative: Install via package manager (includes all pt-* tools):

# Debian / Ubuntu
apt install percona-toolkit

# RHEL / CentOS / Amazon Linux
yum install percona-toolkit
  • Does not modify the system
  • Safe for production
  • Requires OS (shell) access to the server
2

Collect pt-mysql-summary — MySQL config & schema

OS access Read-only

pt-mysql-summary collects MySQL version, configuration variables, storage engines, and schema & index metadata using standard SQL queries only.

wget https://www.percona.com/get/pt-mysql-summary
chmod +x pt-mysql-summary
./pt-mysql-summary --user=advisor --password --host=localhost \
  > server_name_$(date +%d%m%y)_pt-mysql-summary.txt

Alternative: Install via package manager (includes all pt-* tools):

# Debian / Ubuntu
apt install percona-toolkit

# RHEL / CentOS / Amazon Linux
yum install percona-toolkit
  • Read-only — uses SELECT queries only
  • Safe for production
  • Replace advisor with your read-only username
3

Collect SHOW GLOBAL VARIABLES

SQL Read-only

Exports all MySQL server configuration variables to a file. This is required for the core analysis.

mysql -u advisor -p -e "SHOW GLOBAL VARIABLES" \
  > server_name_$(date +%d%m%y)_global_variables.txt
  • Paste the output into the SHOW VARIABLES tab in MySQL Advisor
  • Do not use \G — vertical output is not readable by the analyzer. Use a semicolon or the -e form above, which produces the tab-separated output the tool expects.
  • Or use the Collect data from MySQL panel to fetch it automatically
4

Collect SHOW GLOBAL STATUS

SQL Read-only

Exports runtime status counters — connections, InnoDB metrics, query cache hits, replication lag, etc. Run during normal workload hours for the most accurate analysis.

mysql -u advisor -p -e "SHOW GLOBAL STATUS" \
  > server_name_$(date +%d%m%y)_global_status.txt
  • Paste into the SHOW GLOBAL STATUS tab in MySQL Advisor
  • Do not use \G — vertical output is not readable by the analyzer. Use a semicolon or the -e form above, which produces the tab-separated output the tool expects.
  • Or use the Collect data from MySQL panel to fetch it automatically
5

Collect your schema for Schema Advisor

SQL

Table definitions only, with no rows. Nothing from your application data leaves the server.

mysqldump --no-data --skip-add-drop-table --routines=FALSE \
  -u advisor -p dbname > server_name_$(date +%d%m%y)_schema.sql
  • Paste or upload it on the Schema Advisor page
  • --no-data is what keeps rows out. Check the file before sharing it if you want to be certain
  • To review part of a schema, list the table names after the database name
  • A single CREATE TABLE pasted into the box works just as well
  • The account needs SELECT on the tables being dumped, and SHOW VIEW if the schema contains views
  • Gzipped dumps are accepted, up to 10 MB compressed
6

Create a read-only MySQL user

SQL

Create a dedicated, minimal-privilege user for analysis. No INSERT, UPDATE, DELETE, or DDL permissions are granted.

CREATE USER 'advisor'@'%' IDENTIFIED BY 'StrongPasswordHere';

-- Core privileges
GRANT SELECT, PROCESS, SHOW VIEW ON *.* TO 'advisor'@'%';

-- Optional: replication visibility
GRANT REPLICATION CLIENT ON *.* TO 'advisor'@'%';

FLUSH PRIVILEGES;
Privilege Purpose
SELECT Read metadata and configuration tables
PROCESS View the process list for active queries
SHOW VIEW Inspect view definitions
REPLICATION CLIENT Check replication status (optional)
7

Files to upload to MySQL Advisor

Upload or paste the following files into their respective tabs in MySQL Advisor.

*_pt-summary.txt optional
*_pt-mysql-summary.txt optional
*_global_variables.txt required
*_global_status.txt required
*_schema.sql Schema Advisor
8

Security & Privacy Notes

  • No table data or row contents are collected
  • No passwords appear in any output files
  • Hostnames, IPs, and file paths may appear — review before sharing if required
  • MySQL Advisor processes data server-side and never stores it
  • No external network calls are made during analysis
  • Analysis never connects to your database — it works only on the text you provide
  • The optional Collect data from MySQL panel is the one exception, and only when you use it: the host and read-only credentials you enter are sent to the MySQL Advisor server, which opens the connection and runs SHOW GLOBAL VARIABLES and SHOW GLOBAL STATUS only. The credentials are used for that single request and are never stored or logged. The host must be reachable from the internet; for a database on a private network, paste the output instead

⚠ Before sharing output files

  • Review files for any IP addresses or hostnames you consider sensitive
  • Schema names and table names may appear in pt-mysql-summary
  • Redact as needed before uploading to a shared environment
9

Use the API — analyze from the command line

API key No DB access

Prefer automation? Send the same diagnostic output to the MySQL Advisor API and get findings back as JSON (default) or a Markdown report. One API key covers all three analyzers: the configuration analyzer below, SEIS Advisor and Schema Advisor further down this section. The API never connects to your database — it only analyzes the text you upload. You need an API key to get started.

Don’t have a key yet? Request one with a quick form, reviewed manually. Request an API key →

Fill in the request form with your name, organization, and intended use; your key is emailed once approved.

Step 1 — Collect the data (the two variables and status files are required; the pt-summaries are optional):

# Required: server configuration + runtime status
mysql -u advisor -p -e "SHOW GLOBAL VARIABLES" > global_variables.txt
mysql -u advisor -p -e "SHOW GLOBAL STATUS"    > global_status.txt

# Optional: OS/hardware + schema context (needs Percona Toolkit)
pt-summary                                 > pt-summary.txt
pt-mysql-summary --user=advisor --password > pt-mysql-summary.txt

Step 2 — Set your key and the API URL (run once in your shell):

KEY="mad_your_api_key_here"
API="https://nitty-witty.com/mysql-advisor/api/v1/analyze.php"

Step 3 — Call the API (minimal — required files only, JSON response):

curl -H "X-API-Key: $KEY" \
  -F vars=@global_variables.txt \
  -F status=@global_status.txt \
  "$API"

Full analysis + Markdown report (all four files, saved to advisor_report.md):

curl -H "X-API-Key: $KEY" \
  -F vars=@global_variables.txt \
  -F status=@global_status.txt \
  -F ptsummary=@pt-summary.txt \
  -F ptmysql=@pt-mysql-summary.txt \
  "$API?output=md" > advisor_report.md
  • CLI: cli/mysqladvisor.sh in the repository wraps these steps: it collects via the mysql client, calls the API with MYSQL_ADVISOR_KEY from your environment, and prints the Markdown report
  • Response format: JSON by default; add ?output=md for a readable Markdown report
  • Auth: send your key in the X-API-Key header; a missing/invalid key returns 401
  • Rate limits: requests are throttled per key; exceeding the limit returns 429 with a Retry-After value
  • Privacy: only the text you send is analyzed — no database connection is ever made
  • Replace advisor with your read-only MySQL user and mad_your_api_key_here with your real key

SEIS Advisor via the API

SEIS Advisor has its own endpoint, api/v1/seis-analyze.php, using the same API key as above. It takes SHOW ENGINE INNODB STATUS output instead of variables/status, and its rate limit is tracked separately so the two endpoints don't share one quota.

KEY="mad_your_api_key_here"
SEIS_API="https://nitty-witty.com/mysql-advisor/api/v1/seis-analyze.php"

curl -H "X-API-Key: $KEY" \
  -F seis=@innodb_status.txt \
  "$SEIS_API"

Markdown report instead of JSON:

curl -H "X-API-Key: $KEY" \
  -F seis=@innodb_status.txt \
  "$SEIS_API?output=md" > seis_report.md

Only what needs attention (CRITICAL and WARNING), as Markdown:

curl -H "X-API-Key: $KEY" \
  -F seis=@innodb_status.txt \
  "$SEIS_API?output=md&level=warnings" > seis_warnings.md
  • File upload field: seis (as in the examples above); seis_file also works as an alias
  • Pasted text field: seis_text, sent as a normal URL-encoded POST field instead of a file
  • Size limit: 8 MB, larger than the 2 MB default elsewhere in this API — SHOW ENGINE INNODB STATUS with innodb_status_output_locks=ON can be large
  • Response format: JSON by default; add ?output=md for a readable Markdown report
  • Privacy: only the text you send is analyzed — no database connection is ever made

View — level= controls how much of the analysis comes back:

Level Returns
full (default) Every section and finding — raw section text, transactions and metrics included
issues CRITICAL, WARNING and UNKNOWN findings only
warnings CRITICAL and WARNING findings only

issues and warnings drop sections with nothing to report, and leave out each row’s raw text plus transactions/metrics. summary always counts the whole capture, whatever the level.

Response fields — shared with the configuration API above, plus SEIS’s own:

Field Notes
tool, rules_loaded, version_info, summary, meta Same name and meaning as the configuration API above
rows One entry per InnoDB status section
highlights Top CRITICAL/WARNING findings across the whole capture
flavor Detected MySQL/MariaDB/Percona flavor detail

Schema Advisor via the API

Schema Advisor has its own endpoint, api/v1/schema.php, using the same API key as above. It takes table definitions, either a mysqldump --no-data file or pasted CREATE TABLE statements, and returns one entry per table. Its rate limit is tracked separately from the other two endpoints. The DDL is parsed, never executed.

Step 1 — Dump the definitions (no data, so the file stays small):

mysqldump --no-data --single-transaction -u advisor -p mydb > schema.sql

Step 2 — Call the API:

KEY="mad_your_api_key_here"
SCHEMA_API="https://nitty-witty.com/mysql-advisor/api/v1/schema.php"

curl -H "X-API-Key: $KEY" \
  -F schema_file=@schema.sql \
  -F target=80400 \
  "$SCHEMA_API"

Fail a CI job when the schema would block an upgrade:

curl -sS -H "X-API-Key: $KEY" -F schema_file=@schema.sql "$SCHEMA_API" \
  | jq -e '.upgrade_blockers | length == 0' > /dev/null \
  || { echo "Schema has upgrade blockers"; exit 1; }
  • File upload field: schema_file; a gzipped .sql.gz is accepted and detected from the file contents, not its name
  • Pasted text field: schema_text, sent as a normal POST field instead of a file
  • Target version: target is 80000, 80400 (default) or 90700, and decides what counts as an upgrade blocker
  • MariaDB: add -F flavor=mariadb for a headerless MariaDB dump; a dump header is detected on its own
  • Size limit: 10 MB, the largest of the three endpoints — a definitions-only dump is normally a small fraction of it
  • Response format: JSON only; there is no ?output=md here
  • Privacy: only the text you send is analyzed — no database connection is ever made

Response fields — shared with the APIs above, plus Schema Advisor’s own:

Field Notes
tool, rules_loaded, counts Same name and meaning as the configuration API above
rows One entry per table, worst first, each with its severity, shape, ddl and findings
highlights Up to 10 CRITICAL and WARNING findings across all tables
upgrade_blockers Findings that block an upgrade to the chosen target
document Findings about the dump as a whole rather than one table
input, flavor, target, notes What was received, the detected MySQL/MariaDB flavor, the version reviewed against, and parser level observations

Each finding carries a stable id such as SA_pk_001, safe to build suppressions on. Read label rather than severity when displaying results: an INFO finding with insufficient_data confidence is shown as UNKNOWN. Full field reference in docs/API.md.

Run these commands during normal workload hours for the most accurate analysis.